Agent Chat

agent-chat

agent-chat is the N-agent generalization of the original two-agent codex-chat protocol. The wire format is filesystem state: each graph edge has an append-only CONVO.md, an atomic .turn sentinel, a transient lock, and optional archive/search metadata.

The current runtime model is ephemeral-only. agent-chat init claims a session identity; agent-chat run processes actionable edges and exits. There are no background daemons in the active architecture.

Files

plugins/agent-chat/
  skills/agent-chat/
    SKILL.md
    bootstrap.md
  agents.pair.yaml
  agents.petersen.yaml
  agents.ring.yaml
  agents.star.yaml
  agents.users.yaml
  scripts/
    agent-chat.ts       # init / exit / who / gc / run / speaker / record-turn / role / dots
    turn.ts             # peek / init / lock / flip / park / unlock / recover
    resolve.ts          # print identity and edge paths
    archive.ts          # plan / seal / commit / auto / list
    condense.ts         # fold same-depth archive summaries
    search.ts           # grep / describe / expand / list
    loop-driver.ts      # one tick + ScheduleWakeup or --interactive loop
    notify.ts           # notification-only turn watcher
    autowatch.ts        # autonomous watcher that invokes run ticks
    install-autowatch-systemd.ts # user systemd service installer
    llm.ts              # Claude shell-out helper
    runtimes/claude.ts  # Claude adapter
    runtimes/codex.ts   # Codex adapter

Runtime state defaults to /data/lumeyon/agent-chat/conversations/ and can be overridden by ~/.claude/data/agent-chat/config.json:

{"conversations_dir": "/absolute/shared/path"}

That shared directory is the cross-runtime contract; Claude and Codex sessions interoperate because they read and write the same files.

For Codex after-response capture, the plugin ships a bundled Stop hook at hooks/hooks.json and advertises it from .codex-plugin/plugin.json. On Codex builds where bundled plugin hooks are not active yet, install the compatibility user-level Stop hook once per user:

bun "$AGENT_CHAT_DIR/scripts/agent-chat.ts" install-codex-hooks

That writes ~/.codex/config.toml and ~/.codex/hooks.json, enables the agent-chat plugin entry, points Codex Stop events at this plugin's scripts/codex-stop-hook.ts, and forces the shared conversation root above.

Identity

Each session needs an agent name and topology.

Preferred:

bun "$AGENT_CHAT_DIR/scripts/agent-chat.ts" init  []

Resolution order:

1. Session record under /.sessions/.json.
2. $AGENT_NAME and $AGENT_TOPOLOGY.
3. ./.agent-name.
4. None set: stop and ask the user.

Never infer identity from the model, process name, hostname, or vibes.

Normal Operation

Process pending turns:

bun "$AGENT_CHAT_DIR/scripts/agent-chat.ts" run

Process only selected peers:

bun "$AGENT_CHAT_DIR/scripts/agent-chat.ts" run lumeyon

Run a cache-warm loop:

bun "$AGENT_CHAT_DIR/scripts/loop-driver.ts"

Run an interactive loop:

bun "$AGENT_CHAT_DIR/scripts/loop-driver.ts" --interactive

Run without a human in the loop through the plugin-owned watcher:

bun "$AGENT_CHAT_DIR/scripts/agent-chat.ts" autowatch   --runtime codex

Install that watcher as a restarting Codex-backed user service:

bun "$AGENT_CHAT_DIR/scripts/agent-chat.ts" autowatch-service   --runtime codex

Autowatch refuses to run when a live presence record already exists for the same agent name. This prevents a headless service from composing as an agent while an interactive Claude/Codex session is already on that identity. Use --allow-presence-conflict only when intentionally taking over an agent name.

Manual turn flow:

bun "$AGENT_CHAT_DIR/scripts/turn.ts" peek 
bun "$AGENT_CHAT_DIR/scripts/turn.ts" lock 
# append a Markdown section ending with "→ " or "→ parked"
bun "$AGENT_CHAT_DIR/scripts/turn.ts" flip  
bun "$AGENT_CHAT_DIR/scripts/turn.ts" unlock 

Section Format

##  —  (UTC YYYY-MM-DDTHH:MM:SSZ)

→ 

The arrow line and .turn value must agree.

Directives

agent-chat run parses optional directives after the response section:

updated autobiographical scratchpad
sections: 8
summary: ...
request for that neighbor

updated durable specialty

The directives are stripped from CONVO.md after their effects are applied.

What each directive does (Round 15h+k — see bootstrap.md for the full walkthrough):

• `` — replace this agent's autobiographical scratchpad at

/.scratch/.md. 8 KB cap; older content is archived via scratch-condense.ts.

• sections: N\nsummary: ... — seal the most

recent N sections of CONVO.md into a leaf archive with the agent- authored summary (bypasses the deterministic synthesizer for archives the agent explicitly authored).

• prompt — sub-relay activation:

spawn a sub-tick AS X with this prompt. Only direct neighbors are valid. Cycle refusal + depth ≤ topology diameter as correctness guards.

• `` — Dalio-inspired peer

rating. Default 4 axes (clarity / depth / reliability / speed, each 1-10) but configurable via ~/.claude/data/agent-chat/config.json dot_axes field (1-8 named axes). Stored at /.dots/.jsonl. Self-grading refused. Aggregation is believability-weighted via fixed-point iteration so high-believability voices count more recursively.

• updated specialty — agent self-updates their role

declaration. Stored at /.roles/.md (4 KB cap), overlay- merged into topology.roles on every cmdRun tick so peers see the change immediately. Empty body clears the override and reverts to the YAML default in agents..yaml.

Network roster + relay paths

Every cmdRun tick prepends a roster of every agent in the topology (not just direct neighbors) to the agent's prompt: agent name + role first-line + dot composite + believability + routing hint. Direct neighbors get `; non-neighbors get a "relay through Y" hint computed via lib.relayPathTo` BFS. For petersen (diameter 2) every non-neighbor is reachable through exactly one intermediary.

The mesh becomes self-aware: agents see who specializes in what (by role + dots) and how to reach them (by relay route).

Per-tick auto-archive

agent-chat run calls autoArchiveSessionEdges at the END of every tick. Two gates:

• Parked-AND-bloated past 200 lines — the original threshold.
• Active-AND-very-bloated past 800 lines — defends edges that flip

back-and-forth and never park (e.g. boss-agent edges under record-turn).

Cheap, idempotent, no agent action required.

Human Turns

Humans are defined in agents.users.yaml and overlaid onto every topology. Use:

bun "$AGENT_CHAT_DIR/scripts/agent-chat.ts" speaker 
bun "$AGENT_CHAT_DIR/scripts/agent-chat.ts" record-turn --stdin

record-turn --stdin expects JSON:

{"user":"verbatim user prompt","assistant":"verbatim assistant response"}

It appends the user and assistant sections to the - edge and is idempotent under retry.

Archives

For long conversations:

bun "$AGENT_CHAT_DIR/scripts/archive.ts" plan 
bun "$AGENT_CHAT_DIR/scripts/archive.ts" seal 
bun "$AGENT_CHAT_DIR/scripts/archive.ts" commit  arch_L_...

Search escalation:

bun "$AGENT_CHAT_DIR/scripts/search.ts" grep "query"
bun "$AGENT_CHAT_DIR/scripts/search.ts" describe arch_L_...
bun "$AGENT_CHAT_DIR/scripts/search.ts" expand arch_L_...

Use bootstrap.md for the current operational checklist.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lumeyon
• Source: lumeyon/agent-chat
• License: MIT

Install and usage instructions live in the source repository linked above.