A network of agentic research specialists coordinated by a principal investigator agent. V1: web-search researcher MCP server + CLI shim.
6ff1a6af3d
The loop previously checked the token budget at the *bottom* of each iteration, after the LLM call and tool work had already happened. By the time the cap was caught the budget had been exceeded and the overshoot was unbounded by the iteration's cost. Move the check to the *top* of the loop so a new iteration is never started past the budget. Document the policy explicitly: token_budget is a soft cap on the tool-use loop only; the synthesis call is always allowed to complete so callers get a structured ResearchResult rather than a fallback stub. Capping synthesis is a separate, larger design question (would require splitting the budget between loop and synthesis up-front). Verified: token_budget=5000, max_iterations=10 now stops after 2 iterations with budget_exhausted=True and a complete answer with 10 citations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| cli | ||
| orchestrator | ||
| researchers | ||
| scripts | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| pyproject.toml | ||
| README.md | ||
Marchwarden
A network of agentic research specialists coordinated by a principal investigator agent.
Marchwarden researchers are stationed at the frontier of knowledge — they watch, search, synthesize, and report back what they find. Each specialist is self-contained, fault-tolerant, and exposed via MCP. The PI agent orchestrates them to answer complex, multi-domain questions.
V1: Single web-search researcher + CLI shim for development.
V2+: Multiple specialists (arxiv, database, internal docs, etc.) + PI orchestrator.
Quick start
# Clone
git clone https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden.git
cd marchwarden
# Install
pip install -e .
# Ask a question
marchwarden ask "What are ideal crops for a garden in Utah?"
# Replay a research session
marchwarden replay <trace_id>
Docker test environment
A reproducible container is available for running the test suite and the CLI without depending on the host's Python install:
scripts/docker-test.sh build # build the image
scripts/docker-test.sh test # run pytest
scripts/docker-test.sh ask "question" # run `marchwarden ask` end-to-end
# (mounts ~/secrets ro and ~/.marchwarden rw)
scripts/docker-test.sh replay <id> # replay a trace from ~/.marchwarden/traces
scripts/docker-test.sh shell # interactive bash in the container
Documentation
- Architecture — system design, researcher contract, MCP flow
- Development Guide — setup, running tests, debugging
- Research Contract — the
research()tool specification - Contributing — branching, commits, PR workflow
Status
- V1 scope: Issue #1
- Branch:
main(development) - Tests:
pytest tests/
Stack
- Language: Python 3.10+
- Agent framework: Anthropic Claude Agent SDK
- MCP server: Model Context Protocol
- Web search: Tavily API
License
(TBD)