Jeff Smith 9ecc1db38d chore: add Makefile with venv-based dev workflow

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>

2026-04-08 16:31:00 -06:00

2.5 KiB

Raw Permalink Blame History

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)

2.5 KiB Raw Permalink Blame History