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.
- Get an API key from https://console.anthropic.com.
- 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
1 maintainer
Metadata
1 maintainer
Release files for reflect-mcp 0.7.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| reflect_mcp-0.7.2-py3-none-any.whl | Python 3 | none | any | Details |
Release files / reflect_mcp-0.7.2-py3-none-any.whl
| Download URL | reflect_mcp-0.7.2-py3-none-any.whl |
|---|---|
| Size | 82.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f93b9b27264808a2c9c38337069c48c74e5c2f2347b540e3a0e9aa90fd344e83
|
|
BLAKE2b-256 checksum How to use checksums |
7eba3a681210ce3d772dc8e6d0f49a1c3f6f81e7e97e5812cef3f31855a61f32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for reflect-mcp 0.7.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
