sapling

Sapling

AI-native MCP dev workbench: Postgres-backed knowledge store and typed work queue exposed to Claude Code (and other agents) via MCP.

See the design spec for full rationale.

Quickstart

cp .env.example .env
make up                       # postgres + mcp-server in docker
curl http://127.0.0.1:3333/health

Then install the Sapling Claude Code plugin (slash commands + MCP wiring in one step):

/plugin marketplace add cfarvidson/sapling
/plugin install sapling@sapling

That gives you these /sapling:<name> slash commands:

• /sapling:work — pull next task and execute it
• /sapling:plan <desc> — enqueue a planning task
• /sapling:enqueue <code|review> <desc> — enqueue a code or review task
• /sapling:status — queue health
• /sapling:human [<id>] — list or answer work items paused on user questions (awaiting_input)
• /sapling:queue [<work|plan> <id> [action]] — inspect the queue and run lifecycle actions (activate, archive, update, replace, cancel, block, unblock, retry)
• /sapling:rules [<service> | app <app-name>] [add|replace|remove|clear …] — manage binding rules for an app or service
• /sapling:context <service> — load service context
• /sapling:learn <app> [<path1> ...] — research repos for an app; populate services, dependencies, and an architecture artifact

If you'd rather wire the MCP server up by hand instead of installing the plugin, point your client at the running server:

{
  "mcpServers": {
    "sapling": { "type": "http", "url": "http://localhost:3333/mcp" }
  }
}

Common commands

make up      # start (postgres + mcp-server)
make down    # stop (preserves data)
make logs    # tail mcp-server logs
make psql    # open a psql shell against the running container
make test    # run the test suite (vitest + testcontainers)
make nuke    # stop AND drop data volume + ./data/postgres (5s confirmation)

Updating images & migrating

Migrations run automatically when mcp-server starts (runMigrations in packages/mcp-server/src/index.ts), so updating + migrating is one motion:

docker compose pull postgres        # refresh the postgres:16-alpine tag
docker compose build mcp-server     # rebuild the local mcp-server image (or: make build)
docker compose up -d                # recreate containers; migrations apply on startup
make logs                           # confirm "running migrations"

Notes:

• The postgres service is pinned to postgres:16-alpine. pull only refreshes that tag — it will not bump you to a new major version. For a major upgrade, dump first (pg_dumpall), bump the tag, then restore; the bind mount at ./data/postgres is version-specific.
• mcp-server is built locally, so pull is a no-op for it — use build instead. Add --no-cache if dependencies aren't refreshing.
• Migrations are forward-only and idempotent: each .sql file in packages/mcp-server/src/schema/ runs once, tracked in the _migrations table. To re-run on an already-built image, docker compose restart mcp-server is enough.
• Verify with make psql then SELECT * FROM _migrations ORDER BY applied_at DESC;.

Optional auth

Set MCP_TOKEN=... in .env to require a bearer token on /mcp. Then update your client config:

{
  "mcpServers": {
    "sapling": {
      "type": "http",
      "url": "http://localhost:3333/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Layout

• packages/mcp-server/ — Node/TypeScript MCP server (Streamable HTTP transport, 40 tools)
• packages/claude-plugin/ — .mcp.json template + skills
• packages/runner/ — sapling-runner daemon: polls the queue, spawns coding-agent subprocesses up to max_concurrent, reaps stuck claims each tick

Autonomous mode

sapling-runner is a thin polling daemon that turns a Sapling queue into autonomous coding-agent runs. Each tick it reaps stuck claims, reads the runner config, and spawns up to max_concurrent - running agents via bash -lc <agent_command>. Each spawned agent self-claims via the existing claim_next_work MCP tool.

# Make sure mcp-server is up (`make up`).
make runner                            # foreground; SIGINT/SIGTERM = graceful shutdown
pnpm --filter sapling-runner dev -- --once          # one tick then exit
pnpm --filter sapling-runner dev -- --max-spawn 5   # exit after 5 spawns

The runner reads from SAPLING_MCP_URL (default http://127.0.0.1:3333/mcp) and MCP_TOKEN (optional). Tunable settings live in the runner_config singleton table and are read via get_runner_config at the start of each tick. Change them with the MCP update_runner_config tool: