First-PR scope from #1. Single-process Python daemon that relays
between Claude Code instances and chat-Claude (Anthropic API).
Components:
* relay.config — .env + config.yaml loader. Auto-generates ntfy
topic on first run and persists it back to .env.
* relay.state — atomic file I/O via tempfile + rename, advisory
flock at state/.lock to enforce single-instance.
* relay.conversation — append-only history with summarization.
Triggers a summarize call when total chars exceed
HISTORY_CHAR_CAP (default 400k); replaces history with the
summary plus the most recent 10 turns.
* relay.anthropic_client — SDK wrapper. Marks the system prompt
cacheable (5-min ephemeral cache); concatenates text blocks;
estimates per-call cost from the Anthropic price table with
cache-write/read accounted for.
* relay.queue — JSON envelope intake; oldest-by-mtime;
malformed envelopes moved to queue/.rejected/.
* relay.dispatch — one-input-at-a-time per session
(dispatch/<session_id>/input.txt). Won't overwrite a pending
dispatch; queues internally and waits for CC to delete.
* relay.ntfy — best-effort POST to https://ntfy.sh/<topic>;
failures logged but never block the main loop.
* relay.daemon — main loop. Polls jc_input.txt (priority) then
queue/. Detects [NEEDS-JC] in the first 200 chars of any
response and pauses dispatch until JC writes jc_input.txt.
JC override supports @session-N: prefix for direct dispatch
without an API call.
* relay.__main__ — CLI: relay run / relay status / relay topic.
Tests: 57 unit tests pass (config, state, conversation, queue,
dispatch, anthropic_client, ntfy, full daemon loop with a fake
client). One real-API smoke test marked real_api, opt-in via
pytest -m real_api; skips cleanly on credit-balance errors.
Out of scope for this PR (deferred to follow-ups): Flask status
endpoint, multi-session config in production, exponential
backoff, systemd unit, cost-tracking aggregation.
Closes#1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Initial commit. Establishes:
- .gitignore: .env (secrets), .venv, __pycache__, runtime dirs
(logs/, state/, queue/, dispatch/). Removes the duplicate .env
entry and the .env.example exclusion that was preventing the
example file from being tracked.
- .env.example: ANTHROPIC_API_KEY/MODEL placeholders, NTFY_TOPIC
(auto-generated on first run), STATUS_PORT, HISTORY_CHAR_CAP.
- README: install + run quickstart.
The daemon implementation lands on a feature branch.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
