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)