A network of agentic research specialists coordinated by a principal investigator agent. V1: web-search researcher MCP server + CLI shim.
9ecc1db38d
Targets: make install create .venv and pip install -e ".[dev]" make test pytest inside the venv make test-cov pytest with coverage make lint ruff + black --check make ask run a sample research call make costs show the cost ledger make clean remove venv and caches make docker-build / docker-test parity wrappers for the docker flow Lets contributors get from clone to running CLI in one command without depending on docker. README points at make install as the recommended path; manual venv steps documented as fallback. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| cli | ||
| obs | ||
| orchestrator | ||
| researchers | ||
| scripts | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| Makefile | ||
| 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 (Makefile shortcut — creates .venv and installs deps)
make install
# or manually:
python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
# 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)