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

```bash
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](https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden/wiki/Architecture)** — system design, researcher contract, MCP flow
- **[Development Guide](https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden/wiki/DevelopmentGuide)** — setup, running tests, debugging
- **[Research Contract](https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden/wiki/ResearchContract)** — the `research()` tool specification
- **[Contributing](CONTRIBUTING.md)** — branching, commits, PR workflow

## Status

- V1 scope: [Issue #1](https://forgejo.labbity.unbiasedgeek.com/archeious/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)