Overview
Agent Sessions helps Codex and Claude Code sessions coordinate on one machine. It discovers recent sessions, compares their Git checkouts, and passes messages through a local queue. It also records partner relationships and can preserve a worker's native launch configuration.
What you can do
| Task | Start here |
|---|---|
| Find peers before editing a shared repository | agent-sessions who . |
| Ask one session to take work | agent-sessions send SESSION_ID 'brief' |
| Leave work for a session under a directory | agent-sessions send /path/to/project 'brief' |
| Reserve a received message and reply | agent-sessions claim MESSAGE_ID 'ready' |
| Set up Codex and Claude partners | Partner sessions |
| Keep a worker's configuration on resume | Worker profiles |
How coordination works
- Discover. Read recent host records and current Git state.
whoidentifies
the same checkout and overlapping uncommitted paths.
- Send. Queue a brief for a session or directory. Sending does not start a
model turn or interrupt the recipient.
- Receive. A hook or
inboxshows each session a message once. - Claim. One session reserves the message and sends a reply to its sender.
A received message is peer context. It does not grant permission to edit files, access accounts or execute commands. See the security model.
Sessions, partners and profiles
A session is a discovered native Codex or Claude Code conversation. Recent activity is inferred from host records; a listed session is not necessarily running.
A partner is a recorded relationship between two sessions. One caller can have several Codex and Claude partners. Creating an ordinary Claude partner queues an invitation; creating an ordinary Codex partner uses the Codex app's native tools. Partner sessions explains both routes.
A profile pins explicitly supplied configuration files and a directory. Profiles check launch context and configuration hashes. They do not authenticate workers or establish which tools a host actually exposes.
Next steps
Install the CLI, then follow the quickstart. This documentation covers version 0.2.0.