Usage

chanto                                  # interactive TUI
chanto "fix the failing tests"          # TUI with an initial prompt
chanto -p "explain src/main.rs"         # print mode (non-interactive)
chanto -p --mode auto "add a --json flag and tests"
chanto -p --output-format json "…"      # machine-readable result (usage, duration, num_turns and tool_calls for the whole session, compaction included)
chanto -c                               # continue the last session here (an unreadable one is reported, with the newest readable one resumed instead)
chanto --model qwen3-coder:30b --num-ctx 65536
chanto --provider openai --base-url http://localhost:8080/v1 --model local
chanto --plain                          # line-based REPL instead of the TUI
chanto --worktree fix-auth              # work in a new checkout and branch (see below)
chanto -r                               # pick a previous session to resume
chanto --completions zsh > ~/.zfunc/_chanto
chanto goal "make the importer handle CSV files"   # work until agreed criteria pass
chanto team "add OAuth login and a settings page" --agents 3

Text output (-p without --output-format, or with --verbose) drops terminal escape sequences and control characters from the model's text, whether or not stdout is a terminal, so a reply can't retitle the window or write to the clipboard; json and stream-json carry the text unchanged.

SIGTERM and SIGHUP stop Chanto like an interrupt, in print mode, the TUI and --plain: the running turn ends, the session is saved with your message (and any partial reply) so -c picks it up, and Chanto exits with 143 (SIGTERM) or 129 (SIGHUP). A second signal exits at once.

To drive a multi-turn session from another program, use Claude Code's --input-format stream-json (it needs -p --output-format stream-json, and no prompt argument). Each stdin line is a user message, {"type":"user","message":{"role":"user","content":"…"}}, where content is a string or an array of text blocks and base64 image blocks. Messages run in order as turns of one session: their events stream to stdout, followed by a result event per message. A line that isn't a valid user message gets an {"type":"error",…} event and is skipped. Claude Code's control requests ({"type":"control_request",…}) aren't supported: each gets a control_response with an error, and the session carries on. EOF (or Ctrl-C) ends the session; the exit code is 1 if any message was rejected or any turn failed.

#Claude Code's flags

Scripts written for claude work with these flags, which behave as in Claude Code:

Note that Chanto's --agents takes either form: a number is the team size, as before, and anything else is read as Claude Code's JSON.

#Keys

Messages you type while the model is working are delivered at its next step, as in Claude Code. Large pastes collapse to [Pasted text #n +N lines]; ctrl+o with the cursor on or just after the tag expands it in place so you can edit it, and collapse_pastes = false in config inserts every paste as plain text.

#Prompt extras

• Emoji shortcodes: :tada:, :+1:, :rocket: and other common ones become emoji when you send a prompt (not in pasted text, commands or !shell).
• Pull request status: with the GitHub CLI (gh) signed in, the status line shows the current branch's pull request and what it's waiting on (PR #12 checks failing, approved, changes requested), checked once a minute.
• Prompt suggestions (prompt_suggestions = true, off by default since each one is an extra model call): after a turn, a likely next prompt appears greyed out in the empty prompt; tab takes it.

#Background command output

A Bash call with run_in_background: true, or a foreground command that outlives its timeout, keeps a shell id such as bash_6. The model uses BashOutput to read only new output and KillShell to stop the job. /bashes lists the jobs.

Output polls show the originating command’s short description when supplied, falling back to the command itself:

BashOutput(Build release binary · bash_6)
  ↳ Waiting for new output (up to 30s)

wait_secs waits for new output or exit instead of repeatedly polling; its maximum is 600 seconds. A filter regex waits for matching lines. Results distinguish Still running, Completed · exit 0, Failed · exit N and Stopped, and preview up to three recent lines. Long lines are shortened in the preview; expand the result to inspect more output. A quiet running job says no new output (or no new matching output with a filter). Nonzero exits are marked as errors. For an ongoing stream of notifications instead of explicit polls, use Monitor.

#Background work panel

While subagents run (foreground Task calls, including parallel ones, and background agents), the agents panel under the prompt lists a main row and one row per agent: its type, what it's doing now (its latest tool call or line of text), how long it has run and its tokens so far (input plus output). Background shells follow, using their short description when available and a bounded command preview otherwise. /bashes shows the full commands.

The footer shows the model name without repeating the provider prefix. PR status takes the branch label's place when available; otherwise the branch remains visible. Fully connected MCP servers stay out of the footer; incomplete connections and failures remain visible, with details in /mcp. /model shows the full provider/model selection.

 ● main
 ○ general-purpose  Writing candidates to cand_english.txt     1m 35s · ↓ 36.2k tokens
 ○ Explore          Grep(fn parse_args)                         42s · ↓ 12.1k tokens
 ⚙ npm run dev · bash_1
   ↓ 2 more

At most five lines are shown (three on a short terminal); the rest collapse into ↓ N more and scroll into view with the selection. From an empty prompt, ↓ selects a row (↑/↓ or ctrl+p/ctrl+n move, ↑ past the top goes back to the prompt):

• enter (or a click) on an agent shows its live transcript in place of the main one, and ● moves to it; enter on main, or esc, returns to the main conversation. A background agent started outside a Task call (a /btw fork) shows its latest message instead.
• While you view a background agent, the prompt says Message <type> (<id>)… and what you send goes to that agent rather than the main conversation: a running agent reads it after its current step, and a finished one is resumed with it (keeping its context), as Task with resume would. A foreground agent can't take messages mid-run: the text stays in the prompt with a hint to go back to main. / commands and ! shell commands still run in the main session.
• x stops a background agent or shell, or dismisses a failed row. A foreground agent stops with the turn (esc).
• esc returns focus to the prompt.

A finished agent leaves the panel at once; a failed or stopped one stays 30 seconds. Each agent keeps its last 400 transcript entries for viewing. In inline mode the transcript shows in the live area above the prompt. /tasks and /bashes list background work too.

#Custom keybindings

/keybindings creates ~/.chanto/keybindings.json (or shows where it is). It uses Claude Code's format, so a file written for Claude Code works as is, and with Claude Code compatibility on Chanto also reads ~/.claude/keybindings.json (its own file wins where both bind a key):

{
  "bindings": [
    { "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor", "ctrl+s": null, "ctrl+k ctrl+t": "app:toggleTodos" } },
    { "context": "Confirmation", "bindings": { "y": "confirm:yes", "n": "confirm:no" } }
  ]
}

Keys are ctrl, shift, alt/meta/option and cmd with a key name, case-insensitive (shift+k for Shift+K); a chord is keys separated by spaces, each within 3 seconds; null unbinds a key. Saved changes apply right away, and problems (an unknown action, a reserved key such as ctrl+c, a keystroke Chanto can't read) are listed when the file loads. Contexts Chanto applies: Global, Chat, Autocomplete, Confirmation (permission prompts and questions), HistorySearch and Select. Actions with a Chanto equivalent work (submit, newline, queue and send-now, external editor, image paste, cycle mode, model picker, thinking toggle, history search and navigation, todos, transcript expand, selection copy, stop background agents, exit, and the dialog and list keys); Claude Code actions for screens Chanto doesn't have (its diff panel, agent view, mods' panes, fast mode) are accepted and do nothing, so a shared file stays valid.

#Notifications

When a turn that took longer than notify_after_secs (default 30) finishes, or a permission prompt or question is waiting for you, Chanto sends a desktop notification through the terminal. Terminals that report focus (most do) only get one while the window is in the background. A waiting prompt notifies at once when you're away, and when you switch away later if it's still unanswered. If the terminal doesn't report focus, a prompt notifies after 6 seconds unanswered and a finished turn always notifies. This works in full screen and inline mode.

notifications in config picks how:

In tmux, OSC notifications are wrapped in a DCS passthrough, which needs set -g allow-passthrough on (tmux 3.3+). Messages are reduced to one line with control characters removed, so text from the model can't inject escape sequences. notify_after_secs = 0 turns off the finished-turn notification only.

notify_sound also plays a sound when a finished-turn notification goes out (same timing and focus rules): off (default), default, a system sound name (Glass, Ping… from /System/Library/Sounds on macOS; complete, bell… from /usr/share/sounds/freedesktop/stereo on Linux; a C:\Windows\Media .wav name on Windows) or the path of a sound file. It plays with afplay (macOS), paplay or aplay (Linux) or PowerShell's SoundPlayer (Windows, .wav only).

#Status on the terminal tab

Besides the ✓/spinner tab title (OSC 0), Chanto reports what the TUI session is doing through the Program Status Protocol (OSC 7501), as Claude Code does, so terminals that implement it can show it on the tab: working while a turn runs, blocked (kind permission or question, with the prompt as the message) while it waits on you, then done, or error when the turn failed. Each report is ESC ] 7501 ; state=…:app=chanto[:kind=…][:msg=<base64>] ESC \, sent only when the state changes; the terminal drops working and blocked when Chanto exits.

terminal_status in config picks when: auto (default) sends it only to terminals known to implement it (Ghostty: TERM_PROGRAM=ghostty, TERM=xterm-ghostty) and never inside tmux or screen, so other terminals never see a sequence they might print; on always sends it; off never does. CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 turns it off too, as in Claude Code.

#Keeping the machine awake

A long turn, a /loop or a background run stops when the computer idles into sleep. By default Chanto prevents idle sleep while it's working, and releases it as soon as it's waiting for you. At an idle prompt, the status line shows awake if a background job or the always setting is still preventing sleep.

keep_awake = "working"   # default; or "never", or "always" (the whole session)

It uses caffeinate -i on macOS, systemd-inhibit on Linux (skipped where that isn't installed) and SetThreadExecutionState on Windows. None of them can stop a closed laptop lid from sleeping (unless a Mac is on power with an external display), so for overnight work use a machine that stays on, chanto --bg on a server, or cloud runs.

#Themes

/theme lists the themes and /theme <name> switches for the session (in the TUI, a bare /theme opens a picker). Set theme = "<name>" in config to keep one. Built-in themes: dark, light, dracula, nord, solarized-dark, gruvbox and colorblind. The default, auto, picks dark or light from the terminal background: the terminal's own answer to a background-colour query (OSC 11), else COLORFGBG, else dark. The system appearance is not used, since it says nothing about the terminal's colours; under tmux or ssh, where the query goes unanswered, set theme = "light" if your terminal is light. Plain code tokens always use the terminal's own foreground colour. With NO_COLOR set, the TUI uses no colors at all and keeps only bold, italics and reverse video (inline code keeps its backticks). colorblind is the Okabe–Ito palette, whose colors stay distinct under the common forms of color blindness: its +/- diffs use the blue/orange pair, the safest two, so a diff still reads without color.

Add your own as ~/.chanto/themes/<name>.toml. Start from a built-in with base (default dark) and set only what you change:

base = "nord"            # built-in to start from
background = "dark"      # dark | light: picks the code highlighting (default: the base's)
accent = "#e5a50a"
error = "light-red"

Colors are #rrggbb, #rgb, an ANSI name (black, red, green, yellow, blue, magenta, cyan, gray, dark-gray, light-red … light-cyan, white) or default (the terminal's own color). Keys:

An unknown key or a value that isn't a color is an error naming the key, and Chanto falls back to the default theme with a warning.

#Accessibility

chanto --ax-screen-reader (or screen_reader = true in config, or any of CHANTO_AX_SCREEN_READER, CLAUDE_AX_SCREEN_READER, CHANTO_SCREEN_READER in the environment) runs Chanto for a screen reader: it uses the line-based interface (--plain) rather than the full-screen one, so output arrives in order with no in-place redraws, and it rings the terminal bell instead of the usual notification when a prompt is waiting. Subagents and hooks it starts inherit the mode. Claude Code's axScreenReader setting is read too.

Animations are off whenever a screen reader is on, and otherwise follow the animations config key (--no-animations forces them off): with them off the spinner holds one steady frame instead of cycling, and the line-based frontend prints the working label once instead of repainting it. Left unset, animations follows the macOS "Reduce motion" setting.

#Several sessions in one project

Sessions in different terminals working in the same project know about each other. Each keeps a small record (its latest prompt, the files it edited recently, and a heartbeat) under ~/.chanto/presence/. At the start of every turn the agent is told which other sessions are here and which files they've touched, so it can steer clear. A peer's prompt text is never put in another session's context; only /peers shows the tasks, to you. If it goes to edit a file another live session changed in the last ten minutes, the edit stops once with who has it and why; making the same edit again goes ahead. With the existing check that a file hasn't changed since the agent read it, neither can silently overwrite the other. /peers lists the other sessions. CHANTO_NO_PRESENCE=1 keeps a session out of this entirely (nothing shared, nothing read), for runs that shouldn't be steered by, or appear to, interactive sessions. For work that has to touch the same files at once, start each session with chanto --worktree [name]. It works in a new checkout and branch (chanto/<name>, under .chanto/worktrees/), leaving yours untouched. On exit, a worktree with no changes is removed, otherwise Chanto says how to review, merge or discard the branch. chanto run --bg and /team isolate their agents the same way.

#Inline mode

chanto --inline (or tui = "inline" in config) draws in your terminal's normal screen instead of a full-screen view. Finished output (answers, tool results) is printed once into the terminal's scrollback, so your terminal's own scrolling, search and copy work, including over SSH and in tmux. Only what is still changing is drawn, in a region at the bottom: the end of the answer being streamed, running tools, the to-do list, prompts and dialogs, and the input box.

Differences from full screen:

• ctrl+o prints the most recent finished tool or thinking block again, expanded, instead of opening blocks in place.
• Search with your terminal's find instead of ctrl+f. The mouse belongs to your terminal, so there is no click-to-expand.
• When the window is resized, Chanto clears the screen and reprints the latest output at the new width; older scrollback stays as the terminal rewrapped it. A few lines either side of that point may appear twice. The full transcript is always in the session (/export).
• /clear, /rewind and /resume print the new state below what's already there, since scrollback can't be rewritten.

#Slash commands

/customize /reload /plugin /plugins /help /clear /compact /mode /model /models /think /effort /context /status /cost /usage /skill-doctor /insights /stats /resume /sessions /edit-prompt /rename /title /loop /autocompact /plan /recap /cd /background /rewind /undo /redo /init /review /code-review /simplify /debug /batch /fewer-permission-prompts /security-review /pr-comments /diff /output-style /memory /learned /permissions /allow /deny /sandbox /tools /mcp /hooks /skills /agents /peers /todos /tasks /bashes /fork /share /export /copy /btw /verify /outcome /goal /team /bg /runs /schedule /ide /add-dir /vision /vim /quiet /transcript /voice /theme /statusline /terminal-setup /login /logout /privacy-settings /doctor /feedback /bug /diagnostics /release-notes /upgrade /config /exit, plus your custom commands and skills (/skill-name [args]).

Bundled skills are prompt-based commands shipped in Chanto. A skill or command of your own with the same name replaces one (its alias doesn't: /review always runs the bundled review):

• /code-review [low|medium|high|xhigh|max] [--fix] [--comment] [--max-findings n|all|default] [pr#|branch|range|path] (alias /review): reviews the current branch (commits ahead of upstream, or of main, plus uncommitted changes), or the target you give, for correctness bugs; from high up it also covers duplication, complexity and waste cleanups. low reports a few high-confidence findings; higher levels broaden coverage. Without a level it reuses the last one you typed (stored in ~/.chanto/code-review.json, as is --max-findings), else the session's effort. --fix applies the findings; --comment posts them on the GitHub PR (gh) or GitLab MR (glab). In the interactive UI the review runs as a background agent and its findings arrive when it finishes; in print mode it runs in the foreground. ultra (Claude Code's cloud review) runs a local max review instead.
• /simplify [target]: four parallel read-only reviewers (duplication, complexity, waste and placement) look at the changed code, then the fixes are applied and the tests run. It doesn't hunt for bugs; correctness belongs to /code-review.
• /batch <instruction>: researches the codebase, splits the change into the smallest independent units that can run in parallel (a handful, up to about 30 for a very large change) and presents the plan; once you approve, it runs one background agent per unit, each in its own git worktree (needs a git repository or a WorktreeCreate hook). Each agent implements and tests its unit, commits on its branch, and opens a pull request when the repo has a GitHub remote and gh is signed in; otherwise Chanto offers to merge the branches for you at the end.
• /debug [description]: troubleshoots a problem by reading this session's entries in ~/.chanto/logs/chanto-<date>.log, reproducing it first, and testing hypotheses before fixing the root cause.
• /fewer-permission-prompts: tallies the Bash commands and MCP tools used in this project's saved sessions, picks the read-only ones, and adds them as allow rules to .chanto/config.toml.

/statusline [description] writes a status line script (~/.chanto/statusline.sh, or .ps1 on Windows) from your description, or from your shell prompt (PS1) without one, and sets status_line in ~/.chanto/config.toml (new sessions pick it up). The command gets {"cwd", "model", "mode", "context_used", "context_max"} as JSON on stdin and its first output line is shown.

• /status: one screen with the version, model, provider and where its credential comes from, mode, sandbox, directory and branch, context use, session id and title, this session's tokens and cost, and each MCP server's state. /context breaks the context down, and /context skills (alias /skill-doctor, the name Claude Code uses) lists each skill, subagent definition and connected MCP server with two estimated token costs: its listing, sent with every request (a skill's or subagent's line in the system prompt, an MCP server's instructions and tool definitions, or just a one-line hint per tool that tool search defers), and its full cost once used (a skill's body when loaded, a subagent's prompt in its own context, every MCP tool definition). Rows are sorted by listing cost, so what bloats every request comes first; skills with disable-model-invocation: true cost nothing until run. /doctor checks the setup, including whether the provider is reachable.
• /stats: sessions, prompts, tokens and cost for this project and for all projects over the last 7 and 30 days, then by day (last 7) and by model (last 30), from the saved sessions. Each session counts on the day it was last active, under the model it last used. /cost covers the current session and /insights where its tokens went.
• /rename <title> (or /title): names the session; /resume, its picker and chanto sessions list it by that name. Without a title it shows the current one. Sessions are otherwise named after their first prompt.
• Finding, archiving and deleting sessions: in the TUI, /resume opens a picker you filter by typing (every word must appear in the session's title, first prompt or id). In it, ctrl+d deletes the selected session after asking, ctrl+a archives it (or unarchives an archived one), and tab shows or hides archived sessions (/resume --all opens it with them shown). From the command line, chanto sessions [--search <text>] [--all] lists them, and chanto sessions delete <id>, chanto sessions archive <id> and chanto sessions unarchive <id> manage one (ids may be shortened to a unique prefix); /sessions delete|archive|unarchive <id> does the same inside a session, asking before a delete, and /sessions --search <text> or /sessions --all list. Archived sessions are hidden from the lists (unless GET /sessions?all=true) and chanto -c, but still resume by id, which unarchives them. Deleting removes the transcript and the session's /rewind snapshots (refs in the shadow history no other session uses); it never touches project files. The open session can't be deleted.
• /loop [interval] [prompt]: runs the prompt now and then again in this session (the TUI and the --plain REPL), e.g. /loop 5m check the CI and fix failures. As in Claude Code, the interval leads as a bare token (30m) or trails as every 2 hours; units are s, m, h and d, and seconds round up to whole minutes. Without an interval the loop is self-paced: at the end of each iteration the model calls ScheduleWakeup to pick the next run (1 minute to 1 hour, with a reason shown in the transcript) or to stop the loop when the task is done; an iteration that doesn't reschedule gets one fallback run 20 minutes later, and the loop ends if that one doesn't either. Without a prompt it runs loop.md (.chanto/loop.md or .claude/loop.md in the project, else ~/.chanto/loop.md or ~/.claude/loop.md, read again each iteration) or a built-in maintenance prompt: continue unfinished work, tend the branch's pull request, then a cleanup pass. The prompt can be a slash command (/loop 20m /review). A run that comes due while a turn is running or a dialog is open runs once when it ends; missed runs aren't caught up. The footer shows the next run time and the machine is kept awake while a loop lasts (keep_awake). /loop status shows the loop, /loop stop or esc ends it (ctrl+c while the REPL waits), and loops end on their own after 7 days. There is one loop per session.
• Scheduled tasks: the model can schedule prompts with CronCreate (a 5-field cron expression in local time, recurring or once, e.g. "remind me at 3pm"), list them with CronList and cancel them with CronDelete. Creating one asks for approval in default and accept-edits mode (auto mode's classifier judges it). A scheduled prompt goes to the model as plain text: it can't start with !, / or #, and never runs a shell command, slash command or memory note (your own /loop 5m /command still runs the command; the default loop prompt doesn't). They fire only while the session is open and idle, at most 50 per session, and recurring ones end after 7 days with a final run.
• /autocompact [<tokens>|auto|off]: when this session compacts on its own: a token count (120k, capped at 95% of the context), off (only /compact compacts), or auto (back to compact_threshold). Bare /autocompact shows the current setting.
• Compacting for a smaller context window: /model to a model whose context window can't hold the conversation (it has reached compact_threshold there) asks whether to compact first with the current model, which can still read all of it, switch anyway, or cancel; without a terminal to ask (print mode, --plain scripts) it compacts first. A switch made mid-turn, or one you let through, is handled before the next request: the model that served the last request writes the summary, as Claude Code does. A fallback model with a smaller window is covered too (see Fallback models).
• Idle compaction (idle_compaction = true; off by default, Claude Code's idleCompaction is honoured): when the TUI has sat idle after a turn for idle_compact_minutes (default 54, just under a one-hour prompt cache) and the conversation fills at least idle_compact_percent of the context window (default 0.5; CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS sets a token count instead), Chanto compacts it in the background so your next prompt starts on a short conversation. It runs at most once per idle spell, not while a dialog, background agent or monitor is active, and not when /autocompact off is set; a prompt you send meanwhile waits for it to finish.
• /plan [task]: switches to plan mode, and starts planning the task if one is given.
• /recap: a one-line summary of the session so far from the session's model; nothing is added to the conversation. The TUI also shows one when you come back after 3 minutes away with the terminal unfocused (at least 3 prompts in, never twice in a row); away_summary = false (or CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0, or Claude Code's awaySummaryEnabled) turns that off.
• /cd <path>: moves the session to another directory and keeps the conversation. That directory's instructions, commands, skills, agents, hooks, permission rules and env apply at once (after a trust prompt for an untrusted directory), CwdChanged hooks run, Cd(...) deny rules can forbid destinations, and the session file moves so --resume finds it there. MCP servers from the new .mcp.json start the next time you run Chanto there. Allow rules and extra directories are replaced, not merged: the old project's settings, its saved "always allow" answers, and this session's /allow and /add-dir grants stop applying; your user-level settings, --add-dir directories and the new project's settings apply (its allow rules, additionalDirectories, hooks and env only when the folder is trusted). Deny and ask rules from before are kept, since they only tighten. The auto-mode classifier's auto_mode_rules and fast_path switch the same way (the new project's only when trusted). If the session is in accept-edits mode only because you answered "always allow" to an edit, /cd puts it back in the mode it was in before and says so; accept edits you chose yourself (shift+tab, --permission-mode, the mode setting) stays.
• /background [prompt]: hands this conversation to a background run in its own git worktree (with your uncommitted changes) and frees the terminal; Chanto prints the run id to follow with chanto attach <id>. The prompt, if given, is the run's next instruction; without one it continues the work in progress.

/btw <question> answers a side question from the conversation so far, including mid-turn: it runs alongside the work without interrupting it, and neither the question nor the answer enters the conversation, so tangents don't cost context later. It has no tools. Side questions form a thread (each sees the newest 20 earlier ones) until you clear them. In the TUI the overlay opens as soon as you ask, showing the question with an Asking the side question… progress line while the answer is on its way (a failure replaces it with the provider's reason); the answer then takes its place: ←/→ (or [/]) step through earlier answers, f forks the shown one into a background agent that inherits the conversation plus that question and answer, with full tool access (you keep working; its report comes back as a message, as with any background agent), x clears the thread, and esc closes it. f and x wait until an answer has landed. Bare /btw reopens the overlay; /btw fork [n] forks from the command line.