Metadata-Version: 2.4
Name: reflect-mcp
Version: 0.4.90
Summary: Reflection's autonomous runtime — wake, read prior state, do useful work, write back, sleep.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: anthropic>=0.100.0
Requires-Dist: claude-agent-sdk>=0.1.75
Requires-Dist: croniter>=2.0
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=2.4.4
Requires-Dist: pandas>=3.0.2
Requires-Dist: playwright>=1.59.0
Requires-Dist: plotly>=5.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.0
Requires-Dist: shellingham>=1.5
Requires-Dist: textual<1.0,>=0.63
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.32
Description-Content-Type: text/markdown

# 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

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

## Quick start

```bash
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](#auth-paths) and [Crontab setup](#crontab-setup) below, or read `REFLECT_SETUP.md` inside the new project for the full walkthrough).

Start a single wake manually for testing:

```bash
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:

```bash
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:

```ini
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`:

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

```json
"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:

```bash
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.

```bash
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
