Usage

Command line

Run Chittr from the directory the agents should work in. That directory is the room's workspace. Chittr doesn't search upward for a Git root or a project config.

Options for chittr and chittr resume:

In the resume picker, Up and Down select, Enter opens and Escape cancels. Type to search by message preview or session ID. Page Up, Page Down, Home and End move through long lists.

Shared brief

A brief gives every agent in one conversation the same instructions, from a file.

chittr --instructions-file ./review-brief.md
chittr --new --web --instructions-file ./review-brief.md

• Chittr reads the file once and saves its text with the new chat. Editing or deleting the file later changes nothing.
• Resuming the chat or running /reload keeps its brief, and /new starts without one. /config shows where it came from. You can't change or clear a saved brief, so start a new chat to use a different one.
• The path is relative to the launch directory, absolute, or starts with ~/. Quote paths with spaces.
• A file over 1 MiB, or one that can't be read, stops the launch before any agent starts.
• It can't be combined with resume, --session or doctor.
• The brief takes precedence over room and agent instructions from config. It grants no permissions.

Messages

A plain message goes to every enabled agent. Start it with one or more @names to send it to those agents only.

What's the riskiest part of this migration?
@claude @codex Review src/store.ts for race conditions.

• Only leading @names route a message. An @name later in the text doesn't.
• Every agent sees every message, including messages addressed to others.
• Each addressed agent replies, or passes with a short reason. A pass doesn't prompt other agents.
• @human addresses only you.
• Messages have IDs such as #m2. Commands use them to point at a message.

Pinning sends nothing to agents and doesn't change their context.

Delivery lines show where each message is:

Questions from agents

An agent can ask you a question. A decision question has two to six numbered choices. A free-text question has an input box. The question stays open until you submit an answer.

• Answers are literal. Slash commands and @names inside an answer aren't run or routed.
• Answering never changes permissions or releases a pause. If the asker or the room is paused, the answer waits in the queue.
• /reply discusses a question without answering it.
• You can answer before every opinion from /ask-room arrives. A new round starts only after the previous one finishes.

In the browser, pick a choice or Use this answer to fill an editable draft, or Write a different answer for your own text. Then Send answer. Ask the room does the same as /ask-room.

Pause, stop and recover

Without @agent, a command applies to the whole room. Room and agent pauses are separate, so /continue @codex doesn't release a room pause.

Stop does not roll back file edits or command side effects. Work that already ran stays done.

To recover an agent after a failure:

1. /reconnect @codex
2. /retry #m4 @codex for each failed or interrupted message
3. /continue @codex, then /continue if the room is paused

Chittr never retries a response on its own.

Follow-up turns

Each message you send starts an exchange with eight follow-up turns, shared by all the agents. Set conversation.follow_up_turns to change the number. The agents' first replies to you don't count. Passes and failed or interrupted attempts do. When the turns run out, that exchange stops and other work carries on. /continue #m1 adds another allowance, but a plain /continue doesn't. A /reply from you starts a new allowance.

In the browser, the room buttons pause, stop, continue and quit. Each agent's ··· button opens its own controls. Failed deliveries have retry buttons, and an exchange that ran out of turns offers more.

Saved conversations

Every chat is saved, and chittr always starts a new one.

• Resuming clears pauses, reconnects agents and runs queued messages. Failed and interrupted deliveries still need /retry.
• Saved chats belong to the exact launch directory. A subdirectory or another worktree of the same repository has its own list.
• Chats are stored under ~/.agents/chittr/sessions/<workspace-id>/<session-id>/. Use --state-dir PATH to change the base directory.
• Only one Chittr process can use a workspace's storage at a time.
• An agent whose provider, model, effort or instructions changed starts a fresh provider session, with the saved conversation restored. Grok always starts fresh after a reconnect or restart.

Context compaction

Compaction summarizes an agent's context so it can keep working in a long conversation. The full conversation stays saved.

/compact remember the epic and ticket details
/compact @claude retain the current objective and unresolved questions
/compact -- @claude raised a concern; retain its details

• Codex ignores focus text. Claude and Grok use it. Focus is a request, not a guarantee.
• An agent finishes its current turn before compacting. Other agents keep working.
• Compaction runs while paused and doesn't release the pause.
• /compact codex is rejected in case you forgot the @. /compact -- codex uses "codex" as the focus for every agent.
• If compaction fails, run /reconnect @agent. /stop @agent cancels a compaction in progress.

In the browser, Compact all and Checkpoint are in the toolbar, and Compact context sits beside each agent's context reading.

Images

You can attach images in the browser or the terminal. Permissions, skills and command mode don't affect images, so they work in a default room.

The browser converts any image it can decode to PNG and scales it to at most 2000 px on the long edge, or smaller to fit 3 MiB. The terminal sends files unchanged, so they must already be PNGs within the limits.

In the browser, paste, drop or select images with Attach images. View image opens a larger view.

In the terminal, press Ctrl+O to open the attachment input and run one of these:

Enter runs the action, and Escape returns to the message composer. Staged images are sent with your next message, and a caption is optional.

Which agents can receive images:

An agent that can't receive images gets nothing from that message, not even the caption. The other recipients are unaffected, and the agent still gets text-only messages. Before you send, the composer warns about each recipient that can't receive the images, for example @codex can't receive images. The browser's Details and /attach --status show the reason.

Status and settings

• Context usage is the provider's latest reading in tokens, with a percentage when the provider reports a limit. It isn't cumulative spend.
• Config changes apply on launch, resume or /reload. Agents can't grant themselves permissions mid-chat, so edit the YAML and run /reload.
• /reload restarts the agents a change affects. They keep the saved conversation.

See configuration for the settings themselves.

Browser interface

chittr --web starts a local server and opens your browser. The browser uses the same workspace, config and saved chats as the terminal, and every room command works in its composer. First-time setup still runs in the terminal.

• Keep the terminal process running. Closing or refreshing the tab leaves the agents running, and reopening the printed link reconnects.
• Quit stops and saves the room, like Ctrl+C in the terminal.
• The server listens only on 127.0.0.1, and its link carries a per-launch access token. There's no hosted service.

Keyboard

The terminal renders Markdown in messages. Copying a selection copies the rendered text, not the Markdown source.

File paths

Type ./ in either composer to browse files from the launch directory. Type to filter, use Up and Down to choose, and press Enter or Tab to open a folder or insert a file. Left goes up a folder in the terminal, and Alt+Up does the same in the browser. Escape closes the file list.

The file's path is inserted in backticks. Its contents aren't. Files outside the launch directory and symlinks aren't listed.