The manager
A Claude Code or Codex session you talk to. It is protected and restarts if its process exits. Its record is usually named manager, but the name is yours to choose.
The Karma Yoga CLI · not released yet
One command for every agent session.
The Karma Yoga CLI creates, attaches to, lists and kills agent sessions on your Mac. It ships as one file and works without the app.
The crew
A manager and the agents it starts.
A session is one window. The manager is always the left pane. The column on the right holds the agents the manager starts, each one 20 rows tall, and it scrolls when there are more than fit.
The agents
Up to 12 per session by default. Any mix of Claude Code and Codex works, including only one of them. Each is the real tool, so it behaves the way it always does.
Templates
A template says who sits where. karma new uses the default one unless you name another with --template.
# ~/.karmayoga/karma/config.toml
[templates.default]
manager = "claude"
agents = ["codex", "codex"]
manager_width = 88
[templates.solo]
manager = "claude"
agents = []Talking to the crew
karma agent works on one agent. It creates it in the next slot, reads its screen, parks it, brings it back, sets its goal, interrupts it or sends it a key.
karma crew carries every message between agents. It tells an agent something, shows who is busy or idle, and lists every message with whether it was delivered. An agent inside a session that runs crew gets these commands.
Commands
What each command does.
The first version ships the commands marked v1. Names follow the current design and may change before release.
| Command | What it does | Version |
|---|---|---|
karma new NAME [DIR] | Creates a session from a template, with a protected manager on the left and agents stacked on the right. Takes --template T, such as default or solo. | v1 |
karma attach NAME | Attaches this terminal to the session. Inside a session it switches instead of nesting. | v1 |
karma ls | Lists the sessions on this Mac, with --json for scripts. | v1 |
karma kill NAME | Stops the session's processes and deletes the session. It is the only way to stop a session, because the manager is protected. | v1 |
karma agent create NAME | Creates an agent in the next slot of the session, or in a new bare session when run from a plain shell or a script. Takes --cli claude or codex, --model, --effort and --dir. --prompt holds a first task until the agent is ready, and --wait waits for the reply and prints it. | v1 |
karma agent see NAME | Reads the agent's screen without changing it. | v1 |
karma agent deactivate NAME | Parks the agent and keeps its conversation for later. --force parks it while it is busy. | v1 |
karma agent reactivate NAME | Resumes a parked agent where you call it from, in a new slot inside a session or in a new bare session from a shell. | v1 |
karma agent goal NAME [GOAL] | Reads, sets or clears the agent's own goal. Takes --clear, and --keep to keep an existing goal instead of replacing it. | v1 |
karma agent interrupt NAME | Stops the agent's current turn with Escape. | v1 |
karma agent key NAME KEY | Sends one menu key, such as Enter, Escape, Up or Down. | v1 |
karma crew tell NAME TEXT | Holds a message until the agent is ready, then delivers it. --interrupt stops the current turn first. | v1 |
karma crew status | Shows the agents, who is busy or idle, and the messages still waiting. | v1 |
karma crew history [NAME] | Lists messages and whether each was delivered, the latest 50 unless --limit says otherwise. | v1 |
karma doctor | Checks Claude Code, Codex and the built-in session server, and prints their versions. | v1 |
karma usage | Shows each five hour and weekly window, how much of it is used and when it resets. | coming |
The manager
One conversation per session, for life.
The manager conversation is the session's identity. The Karma Yoga CLI records its id when it creates the session and always resumes that id.
Pinned by id
The Karma Yoga CLI starts Claude Code with an id it chooses and resumes with that id. It never picks up the most recent conversation in the folder, so two sessions in one folder stay apart. Codex conversations are resumed by their id in the same way.
Kept going
Auto compaction keeps a long conversation going, so a session created today is the same conversation a year from now.
Blocked commands
When /clear, /new or /logout is typed in a session pane, the Enter is swallowed and the pane shows that it is blocked in Karma Yoga CLI sessions. Neither tool has to cooperate.
A safety net
If a conversation changes anyway, the Karma Yoga CLI notices the new id, shows a warning and resumes the pinned conversation.
The agents
Claude Code and Codex, each with its own module.
Everything that depends on how a tool behaves lives in one module per tool. The rest of the Karma Yoga CLI asks the module and never reads a screen itself.
What a module knows
How to start and resume the agent, which model and account it runs, whether it is busy or idle, what is in its input box, whether a message was received, and which prompts are blocking it.
Each module is tested against the latest release of its tool, so after every update it is clear what works and what does not.
Its own installs
The Karma Yoga CLI downloads a pinned version of Claude Code and of Codex from their official sources into ~/.karmayoga/tools. Nothing is bundled, so neither tool is redistributed.
Agents it launches have their own login. You log in once inside the Karma Yoga CLI, and logging out of your own claude or codex does not touch it.
No surprise updates
Agents start with their self update turned off, so a tool never changes under a running session. The Karma Yoga CLI installs a new release next to the current one, runs that tool's module tests and switches only when they pass. The previous version stays on disk.
Locked settings
The Karma Yoga CLI ships one policy file with its settings for Claude Code and Codex. It is applied at launch, so changes made from inside a session do not stick. Claude agents also have shell commands such as a forced git push rejected.
[blocked.input] commands = ["/clear", "/new", "/logout"] [blocked.shell] patterns = ["git push --force*"]
Where things live
Each session keeps its own folder.
On your Mac
The Karma Yoga CLI points Claude Code and Codex at a folder per session, such as ~/.karmayoga/sessions/NAME/claude. Transcripts, settings and history stay there, so every conversation belongs to the Karma Yoga CLI and is backed up with it.
Your own tools stay yours
The policy applies only to the Claude Code and Codex that the Karma Yoga CLI launches. Running claude or codex in your own terminal still uses ~/.claude and ~/.codex, untouched. It never writes machine wide or user level settings.
Linked Macs later
Two Macs signed in to the same account behave as one. Every session on either Mac appears in the list on both, and a session can message any manager by name.
The account service later
It holds accounts, each Mac's public key and a directory of session names, which Mac each is on and whether it is busy or idle.
One binary
One file. One background process.
One file to copy
The Karma Yoga CLI is written in Rust and ships as one binary. On another machine it needs nothing installed, and sessions there keep running when the connection drops.
One process in the background
A server owns every pane and keeps it alive. Everything else is a command that starts, does its job and exits. When an agent's process exits, the server keeps the pane and starts the agent again in the same conversation.
The app wraps the CLI
The Karma Yoga app never does anything the CLI cannot. Every feature starts as a Karma Yoga CLI command with --json, and the app adds the interface.
Skills included
The Karma Yoga CLI skills ship inside the binary, so every agent in a session knows the karma commands without setup.
See a first session.
The guide walks through one session from start to finish.