hardline-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

hardline-mcp — working notes

The README explains what this is. This file is for working on it: the conventions, the gotchas that cost real time, and the rules the code already follows so new code follows them too.

Commands

python -m pip install -e ".[dev,codex-watch]"   # codex-watch un-skips the Codex wake tests
python -m pytest tests/test_sessions.py -q      # one module
python -m pytest "tests/test_identity.py::test_verified_owner_token_survives_later_probe_failure" -q
python -m pytest -q -rs -n auto                 # full suite, as CI runs it
python scripts/mutate.py [case ...] [--jobs N]  # regression mutations (tests/mutations/*.json)
hardline-mcp report [--db PATH]                 # read-only audit of a store (report.py)

No linter or formatter is configured. CI (.github/workflows/ci.yml) runs three jobs side by side: the suite on Ubuntu + Windows + macOS, Python 3.10 and 3.14, in xdist workers, then an import of hardline_mcp.server to check that the tools register; the mutation catalog once; and the live sandbox tests on Linux and macOS. Don't run hardline-mcp by hand to test it. It is a stdio server and blocks waiting for input.

Module map

Dependencies point one way: procid <- mailbox <- jobs/sessions <- watch <- server.

• cli.py picks the subcommand (serve / watch / watch-codex / report) before importing anything heavy, so the watchers never load mcp or websockets unless they need them.
• server.py is the only module that imports mcp. Everything else is pure logic that takes an injectable db_path/now_fn, so tests can drive it directly. Every tool is async def and runs its blocking body through _in_thread (anyio.to_thread). A sync tool would block the event loop, pings included. mcp is pinned <2.0.0: 2.x removed mcp.server.fastmcp.
• mailbox.py owns the SQLite connection, WAL, the messages table, and SCHEMA_VERSION. jobs.py (jobs table) and sessions.py (agent_sessions) reuse its _connect/_resolve_db. All three tables are in one file on purpose, so a job's result and its inbox notice can commit in one transaction.
• procid.py handles liveness (ALIVE/DEAD/UNKNOWN) and creation-time process keys, Windows included.
• adapters.py spawns the agent CLIs (hermes chat, codex exec, claude -p). It resolves the executables, sets sandbox/read controls, and decodes output. dispatch.py is the cancellable executor behind ask_*_async.
• github_context.py is pure logic for github=: collect a PR through an injected gh runner, store snapshots content-addressed on disk, and render what one reviewer receives. adapters.py supplies the runner (under the call's on_spawn) and pipes the result to the child's stdin.
• watch.py is a read-only, level-triggered observer of unread mail (what Claude's Monitor uses). wake_codex.py forwards the same observations to a bound Codex app-server thread.
• channel.py decides what to push into a Claude Code session and when (pure logic, no MCP import); delivery.py records push facts and derives receipted/awaiting/unreceipted. server.serve serves through server.serve_streams - FastMCP's own Server.run with channel.tap and the pusher spliced onto the raw streams - not mcp.run(). See docs/push-delivery.md.
• announce.py is the notice wake beside the pusher in the same loop: one constant notice outstanding until its own receipt returns, new mail only. Two subclasses supply the address and transport:
  • claude_inbox.py posts into the Claude Code session's own cross-session inbox (the pipe and token in hardline's environment, proven the host's by ~/.claude/sessions/<pid>.json). It replaces channel push whenever the inbox is proven; push is the fallback. See docs/claude-inbox-wake.md.
  • codex_queue.py pins the Codex thread from tools/call _meta (through the tap's on_call hook), steers a notice into the turn that last called hardline (codex_steer.py: turn/steer on the local daemon, over codex app-server proxy), and queues with codex queue when the daemon refuses. See docs/codex-queue-wake.md.
• hints.py remembers which Claude conversation last held each claimed name (lane_hints), so a relaunched or reconnected conversation is told about its old names and their mail. Advice only: it never claims, routes or reads. See docs/session-continuity.md.
• bindings.py records which Codex thread each claimed name belongs to (thread_names), written only by attributed claims, restorations, releases and dismissals. A Codex server's wake poll claims its thread's names back through the ordinary ownership rule (sessions.survey/sessions.restore, server._restore_pending), and async admission refuses a result addressed to the parent-derived lane while the thread has names the server does not hold. See "A Codex thread's names" in docs/session-continuity.md.
• report.py audits a store read-only (mode=ro, one snapshot, never mailbox._connect): which revisions the registered servers run (recorded in process_revisions, keyed by process identity), whether the legacy sessions table still has live writers, and who acked each job notice against who dispatched the job. Evidence, not verdicts: see docs/architecture.md, "Who acked a message".