marchwarden/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

```bash
# Clone
git clone https://forgejo.labbity.unbiasedgeek.com/claude-code/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>
```

## Documentation

- **[Architecture](docs/wiki/Architecture.md)** — system design, researcher contract, MCP flow
- **[Development Guide](docs/wiki/DevelopmentGuide.md)** — setup, running tests, debugging
- **[Research Contract](docs/wiki/ResearchContract.md)** — the `research()` tool specification
- **[Contributing](CONTRIBUTING.md)** — branching, commits, PR workflow

## Status

- V1 scope: [Issue #1](https://forgejo.labbity.unbiasedgeek.com/claude-code/marchwarden/issues/1)
- Branch: `main` (development)
- Tests: `pytest tests/`

## Stack

- **Language**: Python 3.10+
- **Agent framework**: [Anthropic Claude Agent SDK](https://github.com/anthropics/anthropic-sdk-python)
- **MCP server**: [Model Context Protocol](https://modelcontextprotocol.io)
- **Web search**: Tavily API

## License

(TBD)