Guide

Install

The recommended install is with your agent. Paste Go to getkarmayoga.com/agent and install Karma Yoga. into Claude Code or Codex. Your agent runs every step, and you only sign in.

To install by hand, use the install tabs for macOS, Linux or Windows through WSL2. On macOS and Linux, use the install script, Homebrew or an archive from GitHub Releases. On Windows, run the install script inside Ubuntu.

Set up once

If your agent installed Karma Yoga CLI, this is already done. By hand, install a tool, sign in and set up. Use codex for Codex, and --tools both for both.

$ karma doctor install claude
$ karma auth login claude
$ karma init --tools claude
$ karma new demo --default-dir
$ karma open demo

After setup, karma opens the menu. karma init asks nothing. If something fails, it stops and names the command that fixes it.

Agents run with auto permissions by default, so each tool's own reviewer approves what it would ask you. With bypass, nothing is asked and nothing is sandboxed. Your own Claude Code and Codex permission settings do not apply to agents. Change it with karma settings set claude.permissions bypass or by running karma init again.

Start a session

A session is one area of your life or work. Run karma new NAME to create one and open it. Replace NAME with a name like reports. A name already in use is refused before anything changes. In a terminal, seven steps show creation, startup, manager setup and the assistant's reply before the session opens. Press Ctrl-C to leave it starting in the background, then use karma open NAME to return.

karma new reports

The tools used by the session must be signed in. If a session cannot start because Claude Code or Codex is not signed in, karma new names the tool and tells you how to sign in. Follow those instructions, then stop the session with karma stop NAME and open it again with karma open NAME. It keeps its name and agents.

Choose a working directory when asked. It starts as your current directory, so press Enter to use it or type another path. A missing folder is created once you say yes. Existing files stay.

The manager sits on the left. It is Claude Code or Codex. Give it work by typing in its pane. It creates and directs the other agents, and you can talk to any of them too.

assistant, build the CSV export.
tester, cover empty and large reports.
reviewer, review the diff when tests pass.

Reading the reports page.

Writing export tests.

Waiting for the tests to pass.

Agents learn who they are with the first message they receive. The manager gives them their work.

Give it the whole job.

Add a CSV export to the reports page. Build it, test it, have it reviewed.

Use the session

One bar sits at the bottom. It shows the version, the session name, uptime, agent states and available keys. Uptime starts when you create a session or bring a stopped one back. The agent summary drops first when space is tight. The session name is also your terminal tab title.

Press Ctrl-\ to detach. The session keeps working. Ctrl-Shift-Left goes to the previous session and Ctrl-Shift-Right to the next. The bar shows these keys only when more than one session exists.

Move the pointer into a pane to select it, so your typing goes there. Drag the divider to change the manager's width. The width survives a restart. Ctrl-C never reaches an agent. Press Escape to interrupt a turn.

Agents share the column's height equally. By default, the column scrolls when each pane would have fewer than 11 rows. Ctrl-Shift-Up and Ctrl-Shift-Down select the agent above or below and scroll the column to show it. An arrow in the bar fades when there is nowhere to go.

Terminal.app and iTerm do not pass Control and Shift with the arrow keys, so there the bar shows F5 to F8 in their place. Those keys work in every terminal.

Use the wheel inside a pane to scroll its history. Over a name row it scrolls the agent column, and over the bottom bar it selects the agent above or below.

The manager's name is green. Agent names take yellow, blue, purple, white, cyan, pink, red, lime, magenta, lavender, mint and sky in order. The selected pane has an orange border.

Detach and open again

Close the terminal or press Ctrl-\ whenever you like. The work keeps going. Sessions and agents survive a reboot. They return after you sign in when automatic startup is available. On a Mac without a desktop login, or Linux or WSL2 without a systemd user manager, karma new starts the sessions itself and prints a warning once. In this setup, sessions do not restart automatically after a crash or reboot. Run karma open NAME to bring one back.

Open a terminal outside the session. Run karma ls to list your sessions, including stopped ones. Run karma open NAME to return to one. Opening a stopped session brings it and its agents back on their conversations. karma o NAME is short for karma open NAME.

$ karma ls
SESSION  STATE    MANAGER  BUSY  IDLE  PARKED  DIRECTORY
────────────────────────────────────────────────────────────────
reports  running  idle     2     1     0       ~/projects/reports
────────────────────────────────────────────────────────────────
Agent counts exclude the manager.

karma open reports

If the terminal reports that it lost its connection, run karma ls, then karma open NAME. When you create a session, Karma Yoga CLI saves its environment. Restored agents use it after a reboot or update.

Run the commands below from a terminal outside the session too.

Change your settings

karma settings shows your settings. Set model, effort and permissions for each tool. Each tool keeps its own updater.

karma settings
karma settings set claude.effort high
karma settings set codex.permissions bypass

Agents pick up changes to their defaults when they are idle. Managers use the new settings the next time they start.

layout.min_pane_rows sets the fewest rows each agent gets before the column scrolls. The default is 11.

karma settings set layout.min_pane_rows 12

These settings change the session keys.

Run karma settings set keys.detach KEY with a key such as F5, PageUp, Up or one character. Add C- for Control, M- for Option or Alt, or S- for Shift. Each action needs a different key.

karma settings set keys.detach C-x

Layout and key changes appear in open sessions within a few seconds.

Check your setup

karma doctor checks Claude Code, Codex, sign-in and permission modes. It also reports session health and where to find the logs.

On Linux, Supervisor idle; karma new starts it means no sessions need to run.

$ karma doctor
Karma Yoga CLI 0.3.1 (release)

✓ Claude Code 2.1.309 at ~/.local/bin/claude, signed in.
✓ Codex 0.164.0 at ~/.local/bin/codex, signed in.
✓ Sessions ready: 1 running, 0 stopped.

Logs are at ~/.karmayoga/karma/logs

✓ Your setup is ready.

Repair your setup

Run karma doctor --fix to repair setup problems. It installs a missing Claude Code or Codex with its official installer at https://claude.ai/install.sh or https://chatgpt.com/codex/install.sh, at the newest version tested by Karma Yoga CLI. The installers put their commands in ~/.local/bin by default. If that directory is not on PATH, follow the printed instructions and open a new terminal. An existing native or npm copy outside the tested range is reinstalled at the tested version. A Homebrew copy outside the range is kept with a warning.

karma doctor --fix

Start setup again

Run karma doctor reset to reset your settings. It reads the tools' own settings again and writes defaults. In a terminal, it asks the setup questions again. Tools, sessions and conversations stay.

karma doctor reset

Update Karma Yoga CLI

karma update installs the latest release and restarts the running sessions on it. Each agent comes back on its conversation. It asks once before updating. Busy agents are interrupted and told to continue when they are back.

karma update

When Homebrew installed Karma Yoga CLI, karma update upgrades through Homebrew.

Restart your agents

karma restart NAME restarts every agent of a session, the manager too, on its conversation, and tells busy agents to continue. Use it when an agent is stuck, or to give the manager new settings.

--manager or --agent AGENT restarts only that one.

karma restart reports

Rename a session

Run karma rename OLD NEW to give a session a new name. Its agents and conversations stay with it.

karma rename reports work

Stop a session

karma stop NAME stops a session and its agents while keeping their records and conversations. It stays stopped after a reboot. Run karma open NAME to bring it back, or karma start NAME to start it without opening it.

karma stop work

Remove a session

karma delete NAME removes a stopped session's records, log and saved conversation links. Its working directory and the tools' transcripts stay. You cannot bring the session back after deleting it.

karma delete work

It asks before removing the session. --yes skips the question and is required when the command cannot ask.

Uninstall Karma Yoga CLI

Stop every session first. Then run karma uninstall to remove the binary and the service that keeps sessions running. It asks whether to delete your settings too. Your sessions' records and conversations stay. Reinstall and use karma open NAME to return to them.

karma uninstall

When no sessions and no settings remain, it also removes ~/.karmayoga/karma. With Homebrew it leaves the binary, and brew uninstall karma removes it.