reflect-mcp 0.5.1

Reflection's autonomous runtime — wake, read prior state, do useful work, write back, sleep.

reflect

Autonomous agent runtime. Wake, read prior state, do useful work, write back, sleep.

Reflect runs on the Claude Agent SDK and is designed to operate continuously in the background — scheduling itself, reading inbox messages, executing work across independent tracks, and persisting state between sessions.

Ships four binaries: reflect (operator CLI), reflect-wake (wake loop runner), reflect-dispatch (cron dispatcher), reflect-manage (MCP server).

Install

uv tool install reflect-mcp
# or
pip install reflect-mcp

Quick start

reflect init my-project
cd my-project

Edit concept.md — it's the first thing the agent reads.

Then install the wake schedule (see Auth paths and Crontab setup below, or read REFLECT_SETUP.md inside the new project for the full walkthrough).

Start a single wake manually for testing:

reflect wake start main

Auth paths

Wakes run as Claude Agent SDK completions. Three credential schemes are supported.

Subscription path (default — personal / dev use)

Routes through a local OAuth proxy that reads ~/.claude/.credentials.json (created by claude login). Bills against your Claude Max subscription.

⚠ ToS note: subscription auth is appropriate for personal, hobbyist, or exploratory use. For production, commercial, or customer-facing deployments use the API path.

Start the proxy daemon:

reflect proxy
# persistent: nohup reflect proxy &

Health check: curl http://localhost:9000/health

API path (production / commercial use)

Bills against the Anthropic API directly. No proxy needed.

1. Get an API key from https://console.anthropic.com.
2. Save to agent/secrets/anthropic.api_key (mode 600, no trailing newline).

AWS Bedrock path (experimental — v0.4.1)

Routes through AWS Bedrock. Set REFLECT_CREDENTIAL_SCHEME=aws_bedrock in agent/runtime/reflect.env. Optional: REFLECT_AWS_PROFILE, REFLECT_AWS_REGION, REFLECT_MODEL.

reflect.env

All credential config can live in agent/runtime/reflect.env (gitignored by default). Variables there are loaded as defaults — env vars in the crontab line win. Example:

REFLECT_USE_API=1
ANTHROPIC_API_KEY=sk-ant-...
# or for Bedrock:
REFLECT_CREDENTIAL_SCHEME=aws_bedrock
REFLECT_AWS_PROFILE=my-profile

Crontab setup

reflect-dispatch fires once per cron tick and schedules per-track wakes. Install via crontab -e.

Subscription path:

* * * * * cd /path/to/project && reflect-dispatch >> /tmp/reflect-dispatch.log 2>&1

API path:

* * * * * cd /path/to/project && export ANTHROPIC_API_KEY="$(cat agent/secrets/anthropic.api_key)" REFLECT_USE_API=1 && reflect-dispatch >> /tmp/reflect-dispatch.log 2>&1

Bedrock path: set credentials in agent/runtime/reflect.env and use the subscription-path crontab line (reflect.env is loaded at dispatch startup).

Verify the schedule is running: reflect doctor.

Wiring into Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "reflect": {
      "command": "reflect-manage"
    }
  }
}

Restart Claude Code. Eight MCP tools become available:

Tool	Primary actions
track	list, status, send, logs, interrupt
track_admin	create, enable, disable
project	list, link, unlink
wake	status, history, start, stop
inbox	list, peek, timeline
cost	usage by track + time range
doctor	basic health check
reflect_doctor	structured JSON health payload

Project routing: reflect-manage walks up from Claude Code's cwd looking for a directory containing agent/runtime/tracks/. To force a specific project regardless of cwd:

"reflect": {
  "command": "reflect-manage",
  "env": { "REFLECT_PROJECT": "/absolute/path/to/your/project" }
}

CLI reference

# Init + dispatch
reflect init <name> [--path <dir>]
reflect dispatch [--dry-run]
reflect proxy [--host] [--port] [--credentials]

# Track management
reflect track list
reflect track status <name>
reflect track tail <name> [--no-follow]
reflect track logs <name>
reflect track enable <name>
reflect track disable <name>
reflect track create <name> [--template blank|<auditor>] [--cadence-seconds N]
reflect track send <name> <message>
reflect track interrupt <name> <message>
reflect track session <name> [--replay N]

# Project management
reflect project link <path>
reflect project list
reflect project unlink <name>

# Wake control
reflect wake list
reflect wake start <track> [--force]
reflect wake stop <track>
reflect wake history [<track>] [--limit N]

# Events + webhooks
reflect events list [--limit N] [--track] [--type] [--since]
reflect events since <timestamp>
reflect events tail [--track] [--type] [--lines N]
reflect webhooks list
reflect webhooks add <url> [--event-type] [--track]
reflect webhooks remove <id>
reflect webhooks test <id>

# Observability
reflect inbox [<track>] [-i/--interleave] [--pending-only] [--limit N]
reflect doctor
reflect cost [--by-track] [--since]
reflect dashboard
reflect completion [--install] [--shell bash|zsh|fish|powershell]

# Global flags
-o, --output human|json
--no-color / --color

Multi-project model

One reflect-manage instance can serve multiple projects. Each project is a standalone repo; link it from a central orchestrator with:

reflect project link /path/to/project

This creates an agent/projects/<name> symlink in the orchestrator and writes a reverse-pointer marker at <project>/agent/runtime/orchestrators/<hash>.path.

Nested projects (v0.4.2): if the project already lives inside agent/projects/<name> as a real directory (not a symlink), reflect project link writes only the marker — no symlink created. reflect project list shows kind: nested for these rows.

reflect project list          # audits all links; all entries should show status: ok
reflect project unlink <name> # removes symlink + marker
reflect doctor                # validates orchestrator markers

What reflect init creates

<name>/
  concept.md           # what the agent is for — edit this first
  wake.md              # agent constitution (3 bootstrap entries)
  AGENT.md             # project structure + running instructions
  REFLECT_SETUP.md     # one-time operational setup (crontab + auth paths)
  .gitignore
  agent/
    design/            # design docs
    reports/           # wake reports
    inbox/
      .consumed/
    runtime/
      wakes.tsv
      tracks/
        main/          # primary agent track
          wake.md
          inbox/
          followup/
        originator/    # human track — no wake supervisor
          human.flag
          inbox/

REFLECT_SETUP.md inside the new project has the full one-time setup walkthrough with exact crontab lines and auth path details.

Status

v0.4.2. Core runtime (track/wake/inbox/dispatch/MCP) is production-stable.

Experimental features:

• AWS Bedrock auth (v0.4.1, Phase 1) — credential scheme wired; not battle-tested at scale
• Nested projects (v0.4.2) — symlink-free linking for nested repo layouts; just shipped
• Events + webhooks — functional; stability not validated

License

MIT