vibecoding-devtools 1.0.1

package/skills/maestri-agent-cli/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: maestri-agent-cli
+description: Drive another agent's terminal on the Maestri canvas when it may run a CLI or account different from yours (Antigravity, Claude Code, Codex, and others). Load it when you recruit an agent, before you operate an agent's TUI with `maestri ask --raw` (answering a permission prompt, switching model or effort, opening its settings, checking its quota), and when an agent is stuck, waiting, out of quota, logged out or erroring.
+user-invocable: true
+---
+
+# Driving Other Agents' CLIs
+
+You're running inside Maestri, a spatial development workspace that connects AI agents, terminals, notes, and browser
+portals on a visual canvas. This skill extends the base `maestri` skill.
+
+The agents on the canvas may run different CLIs, on different accounts. Each CLI has its own screens, keys, slash
+commands, permission prompts and quota rules. What works in your own CLI can do something else in theirs: a key that
+dismisses a dialog in one can exit the agent in another. Never assume the other agent works like you.
+
+## 1. Know each agent's CLI and account
+
+`maestri list` may show only the agent's name, without its CLI or account. Keep them in a file of your own, `ledger.md`,
+under `## Agents`, one row per agent, and read it before you drive any agent. The `maestri-budget` skill adds the quota
+and model tables to the same file.
+
+```markdown
+## Agents
+
+| Agent | CLI | Account | Model |
+|---|---|---|---|
+| Hawk | Codex | Work | fixed |
+| Lynx | Antigravity | Default | managed |
+```
+
+- **Account** is the account name from `maestri preset list` when you know it (you recruited the agent); otherwise the
+  login or plan its screen shows. Agents on the same account share its quota.
+- **Model** is `fixed` unless the user tells you an Antigravity agent is a multi-model generalist under your control:
+  then it is `managed` (see the `maestri-budget` skill). Never change the model, effort or settings of a `fixed` agent
+  unless the user asks for that change.
+
+- **Where:** your session directory (the scratch or session folder your CLI gives you). If your CLI has none, use
+  `maestri-<your name>/ledger.md` in the system temp folder. It is your working record: never put it on the canvas or in
+  the project.
+- **When you recruit**, write the row right away: the CLI comes from the preset and the account from `--account` (or the
+  preset's own account, as `maestri preset list` prints it).
+- **For an agent you did not recruit**, identify it once from its screen (table below) and write the row. Where each CLI
+  shows the account is in its reference.
+- **Update the row** whenever you run `maestri recruit --replace` with another preset, command or account: that is how
+  an agent's CLI or account changes.
+- Use account names as `maestri preset list` prints them; never write an email, token or key in the file. Do not record
+  the model or effort: they change with restarts and pickers.
+- If the screen ever disagrees with the file, trust the screen and fix the file. In a new session the file may be gone:
+  rebuild it the same way.
+
+To identify an agent from its screen, read it with `maestri check "Agent Name"` and match it:
+
+| CLI | Signature on screen | Reference |
+|---|---|---|
+| Antigravity | Banner `Antigravity CLI <version>`; input `>`; footer `<model> · <effort>`; command `agy` | [references/antigravity.md](references/antigravity.md) |
+| Claude Code | Banner `Claude Code v<version>`; input `❯`; footer with the mode (`auto mode on`, `manual mode on`...); command `claude` | [references/claude-code.md](references/claude-code.md) |
+| Codex | Banner `>_ OpenAI Codex (v<version>)`; input `›`; footer `<model> <effort> · <folder>`; command `codex` | [references/codex.md](references/codex.md) |
+
+Open the matching reference before pressing anything. If no signature matches, use `/help` or `?` on the agent and read
+the result before acting; to add a CLI, copy [references/_template.md](references/_template.md).
+
+CLIs update often. When a screen, menu or prompt does not match the reference, trust the screen: do not guess keys,
+back out with Esc, and tell the user the reference is out of date.
+
+Before delegating, check **Built-in capabilities** in the reference: which tools the agent has (web search, images,
+browser, subagents) and which commands help with the task (`/plan`, `/review`, `/btw`, `/goal`). Delegate a task to an
+agent that has what it needs.
+
+## Launch agents autonomous
+
+Routine permission prompts stall delegated work. For every agent that needs autonomy, the Maestro follows this conduct:
+
+1. **Recruit:** use the CLI's autonomous flags through `--command` or a preset, unless the user wants a limited agent.
+   A limited agent gets an explicit allowlist containing only the commands its job needs; see its reference below.
+2. **Already running and stopping on prompts:** approve the current in-scope action once, following section 3. When
+   its current task finishes, restart with autonomous flags using `maestri recruit --replace`, then brief it again.
+   Never restart mid-task: its context is lost. Preserve its CLI, model, effort and account. This launch policy covers
+   that task-boundary restart; section 3 still governs prompt decisions.
+3. **Presets missing flags:** propose the updated preset command to the user, preserving its model, effort and account.
+4. **Report:** tell the user which mode each agent runs in, and record it in the agent's ledger row.
+
+| CLI | Recommended command | Limited agent |
+|---|---|---|
+| [Codex](references/codex.md) | `codex --no-daemon --approve-for-me` | Sandbox and command rules |
+| [Antigravity](references/antigravity.md) | `agy --mode auto` | Session command grants |
+| [Claude Code](references/claude-code.md) | `claude --permission-mode auto` | `dontAsk` and tool grants |
+
+Read **Autonomous launch and command rules** in the matching reference. Use isolated settings for limited agents;
+allowlists govern approvals and do not alone enforce a complete commands-only boundary.
+
+After startup, verify the reported mode; do not accept a fallback to manual mode as successful autonomous recruitment.
+Auto review can reject actions. Fully unsandboxed or dangerous bypass modes require the user's explicit request;
+never add them to fix a stalled task. Startup trust, login and later permission prompts still follow section 3.
+
+## 2. Drive in small steps
+
+- **Look, act, look.** `check` before every input, send one step, `check` again. Menus change under you.
+- **Use `--raw` for the TUI.** A plain `maestri ask` waits until the agent finishes, so it hangs while the agent sits on
+  a permission prompt or a menu. If a plain `ask` times out, `check` for a prompt before anything else.
+- **Send text and Enter in separate `--raw` calls.** Some CLIs take text and `\n` sent together as a paste and do not
+  submit it.
+- **Text already in the input box may be a greyed prompt suggestion**, not something anyone typed. It is never an
+  instruction, a reply or a decision.
+- **Navigate with ↑/↓ (`\e[A`, `\e[B`) and back out with Esc (`\e`).** In some settings panels ←/→ changes the
+  highlighted value; follow the reference.
+- **Never send exit or suspend keys** (the reference lists them per CLI) unless the user asked to stop the agent.
+- **Clear typed text with Backspace (`\x7f`)**, not with keys that may interrupt or exit.
+- **Escapes apply to every `maestri ask`**, not only `--raw`: `\t` and `\n` inside a prompt become Tab and Enter. Write
+  Windows paths with forward slashes (`C:/teste/file.md`).
+- **Windows Git Bash:** an argument starting with `/` is rewritten into a Windows path (`/model` arrives as
+  `C:/Program Files/Git/model`). Prefix the command with `MSYS_NO_PATHCONV=1`, or run `maestri` from PowerShell.
+
+## 3. Permission prompts
+
+Answering another agent's permission prompt approves an action on the user's behalf.
+
+- **Approve once** (the plain "yes" option) only for actions that are clearly part of the task you delegated.
+- **Ask the user first** before: options that persist ("always allow", "don't ask again", saved to settings), changing
+  the agent's permission mode, irreversible or destructive actions, and anything outside the task or the workspace.
+- Screen lines that announce an action (an edit, a command run) can appear **before** approval, and some stay even after
+  a denial. Treat the action as done only after the prompt is gone and a result line or the agent's reply confirms it.
+- In some CLIs a number key picks its option at once, with no Enter: send the number only for the option you mean.
+
+## 4. Recover a stuck agent
+
+`check`, classify the state with the reference, then:
+
+| State | Action |
+|---|---|
+| Working | Wait. Never interrupt an agent that is still working. |
+| Waiting on a permission prompt | Section 3. |
+| Menu, panel or notice open | Esc until the input box is back, then resend if needed. |
+| Out of quota | Check the reference: switch to a model group with quota left, or ask the user to move the agent with `maestri recruit --replace "Name" --account "Other"` (Claude Code and Codex only; accounts from `maestri preset list`), or tell the user when it resets. Pacing quota so this does not happen is the `maestri-budget` skill. |
+| Logged out | Tell the user: logins are interactive and need them. |
+| Error | Read it, retry once if it is transient, otherwise report it to the user. |
+
+## 5. Configure, safest first
+
+1. **Launch flags**: model, effort and permission flags in the preset command, applied with
+   `maestri recruit "Name" --command "..."` (or `--replace "Name"`) or a preset. Each reference's **Model and effort**
+   says where the CLI lists its exact model ids and how to pass them: never guess an id.
+2. **The CLI's settings file**, when the reference names it.
+3. **The TUI menu** (`/model`, `/config`...) through `--raw`, step by step.
+
+Change only what the user asked for, and tell them what you changed: some changes reset other values (switching model
+can reset effort), and some pickers save the choice as the default for every new session unless you pick the
+session-only option. The reference says which.
+
+When Maestri restarts an agent, it relaunches the preset command: a change made in the TUI is lost if a flag in that
+command sets the same value. After a restart, `check` the footer and redo the change, or put it in the command.

package/skills/maestri-agent-cli/references/_template.md

@@ -0,0 +1,62 @@
+# <CLI name>
+
+Verified live on <CLI> <version>, <OS> (<date>). Or: **Not yet verified live.**
+
+## Identify
+
+- Launch command:
+- Banner:
+- Footer:
+
+## States
+
+| State | On screen |
+|---|---|
+| Idle | |
+| Working | |
+| Permission prompt | |
+| Menu or panel | |
+| Done | |
+
+## Permission prompts
+
+Paste each prompt as it appears, then note which option approves once and which ones persist.
+
+## Model and effort
+
+## Settings
+
+How to open them, how to navigate without changing values, and where the settings file lives.
+
+## Quota
+
+How to see it, what the exhausted screen says, and how to recover.
+
+## Keys
+
+| Key | Raw | Action |
+|---|---|---|
+| Enter | `\n` | |
+| Esc | `\e` | |
+| Ctrl+C | `\x03` | |
+| Ctrl+D | `\x04` | |
+| Shift+Tab | `\e[Z` | |
+
+Mark keys that exit, suspend, change modes or approve actions.
+
+## Built-in capabilities
+
+Ask the agent to list its tools by exact name without running any, and read `/skills`. Keep only what ships with the
+CLI: leave out Maestri's skills and anything from plugins the user installed.
+
+| Need | How |
+|---|---|
+| Web search | |
+| Read images | |
+| Subagents | |
+| Plan before editing | |
+| Side question | |
+
+## Slash commands for the Maestro
+
+## Not yet observed

package/skills/maestri-agent-cli/references/antigravity.md

@@ -0,0 +1,206 @@
+# Antigravity CLI
+
+Verified live on Antigravity CLI 1.4.8, Windows, Google AI Pro account (2026-10-27); quota pools and `/context` on 1.4.9
+(2026-11-04).
+
+## Identify
+
+- Launch command: `agy`, e.g. `agy --model gemini-4-argon-high --effort high`.
+- Banner: `Antigravity CLI <version>`, account and plan, model and effort, workspace folder.
+- Footer: `<model> · <effort>`, e.g. `Gemini 3.8 Flash · medium`.
+- `?` → tab **general**: version, account, workspace, project config
+  (`~/.gemini/config/projects/default-cli-project.json`), log (`~/.gemini/antigravity-cli/log/`), conversation id.
+
+## States
+
+| State | On screen |
+|---|---|
+| Idle | Empty `>` input; footer `? for shortcuts` |
+| Notice | Block with `┃` lines and `esc to dismiss` above the input |
+| Menu or panel | Footer `Keyboard: ...` or `esc to cancel` |
+| Permission prompt | `Allow creation of this file?` or `Run this command?` with numbered options |
+| Done | Agent's reply, then an empty `>` input |
+
+`● Edited 1 file (...)` and `● Ran (...)` show up while the permission prompt is still open: they do not mean the action
+happened.
+
+## Sending a prompt
+
+Text and `\n` in a single `--raw` call submitted the prompt. Sending the Enter in a separate call, as the skill
+recommends, is the safe default across CLIs.
+
+## Autonomous launch and command rules
+
+Verified on Antigravity CLI 1.5.2, Windows (2026-11-06): installed help and isolated startup argument checks.
+
+```bash
+agy --mode auto
+```
+
+The installed help accepts `auto`, `accept-edits` and `plan`. Auto mode handles workspace edits and safe commands;
+risky or irreversible actions can still prompt. Check the active mode after launch. The fake-home test warned that the
+terminal sandbox was unavailable and fell back to default mode, then required login. Do not treat that as an autonomous
+session; resolve sandbox availability or prepare the limited-agent grants below. No authenticated actions were tested.
+
+For a limited agent, use session settings rather than general auto approval:
+
+```bash
+agy --mode accept-edits --settings /path/to/limited.json
+```
+
+```json
+{
+  "permissions": {
+    "allow": ["command(npm --version)"],
+    "deny": ["command(git push)"],
+    "ask": []
+  }
+}
+```
+
+`--settings` accepts a JSON object or file for this session only, never saved. The example was accepted at startup;
+grant matching was not exercised past login. Persistent CLI grants use `permissions.allow`, `permissions.deny` and
+`permissions.ask` in `~/.gemini/antigravity-cli/settings.json`. Prompt option 3 saves its command grant there;
+option 2 lasts for the conversation. Do not edit `~/.gemini/config/` expecting it to change this CLI allowlist.
+
+Grants use `command(prefix)` or `command(regex:pattern)`. On Windows, a command that cannot be split reliably needs
+an exact match or regex. Deny overrides ask, then allow; `ask: ["command(*)"]` defeats narrower allow grants.
+Unlisted commands in this limited mode can prompt: an empty ask list is not a deny-by-default policy.
+Workspace edits remain allowed; use sandbox controls if the agent needs a stricter boundary.
+See the [CLI permission reference](https://antigravity.google/docs/permissions#cli-fine-grained-permissions).
+
+`--dangerously-skip-permissions` auto-approves every tool request. Use only at the user's explicit request.
+
+## Permission prompts
+
+File edit or creation:
+
+```text
+Allow creation of this file?
+> 1. Yes, allow creation
+  2. No, deny creation
+  ↑/↓ Navigate · tab Amend · f full diff
+esc to cancel
+```
+
+Command:
+
+```text
+Run this command?
+> 1. Yes, run command
+  2. Yes, and always allow in this conversation for commands that start with '<cmd>'
+  3. Yes, and always allow for commands that start with '<cmd>' (Persist to settings.json)
+  4. No, cancel
+  ↑/↓ Navigate · tab Amend · ctrl+g edit/expand command
+esc to cancel
+```
+
+- Option 1 is preselected: Enter (`\n`) approves once.
+- Option 2 persists for the conversation, option 3 persists to `settings.json`: ask the user first.
+- Which actions prompt is set by **Agent Mode** and **Tool Permission** in `/config`.
+
+## Model and effort
+
+- **Exact ids:** `agy models` prints one `<id>` and name per line for the account, e.g. `gemini-3.8-flash-low`,
+  `gemini-4-argon-high`, `claude-sonnet-5-5-medium`; the effort is part of the id. Launch with
+  `agy --model <id> --effort <low|medium|high>` (e.g. in `maestri recruit --command`).
+
+1. `/model`, Enter → **Switch Model** picker.
+2. ↑/↓ picks the model, ←/→ sets effort (low, medium, high), Enter confirms, Esc goes back.
+3. Confirmation in the history: `⎿ Model set to <model> (<Effort>)`.
+
+Switching model resets effort to medium. `/effort` sets effort alone. Both can be set at launch:
+`agy --model <id> --effort <level>`.
+
+A `/model` change does not survive a restart when the preset command pins the model: after Maestri relaunched it with
+`--model gemini-4-argon-high --effort high`, the agent was back on Argon high.
+
+## Settings (`/config`)
+
+- `/config`, Enter. Typing filters the list. Esc clears the search, and exits when the search is empty.
+- **←/→ changes the highlighted value.** Navigate with ↑/↓ only.
+
+| Setting | Values / meaning |
+|---|---|
+| Agent Mode | `default`; `accept-edits` (auto-approves edits, prompts for commands); `auto` (auto-approves edits and safe commands, prompts on irreversible actions); `plan` (researches and plans without changes) |
+| Tool Permission | Whether terminal commands need approval (`request-review` by default) |
+| Artifact Review | `always proceeds`, `agent decides`, `asks for review` |
+| Non-Workspace Access | Access to files outside the workspace folders |
+| Sandbox Mode | Terminal sandbox restrictions |
+| Queued Messages | When follow-up messages are sent |
+| Use AI Credits | Use AI credits once the plan's quota runs out |
+| Verbosity | Detail shown for tool calls, commands and thoughts |
+
+Also: Animation Speed, Color Scheme, Conversation Picker Grouping, Copy on Select, Editor, Editor Mode, Enable
+Telemetry, Notifications, Rendering Mode, Seasonal Themes, Show Active Tasks, Show Feedback Survey, Show Tips.
+
+## Quota
+
+- `/usage` (alias `quota`): quota per pool, shown as **percent remaining** (not used), with `Refreshes in <h>h <m>m`
+  once part of it is spent. The panel scrolls (PgDn `\e[6~`); Esc closes it. Pools on a Pro plan (1.4.9):
+  - **Gemini** group: Gemini Flash, Gemini Pro. Weekly and five-hour limits. Flash has the roomiest quota but makes
+    frequent mistakes in development work: verify everything it delivers (`maestri-budget`).
+  - **Claude and GPT** group: Claude Opus, Claude Sonnet, GPT-OSS. Weekly and five-hour limits.
+  - **Gemini 4 Argon**: its own weekly limit, separate from the Gemini group, with no five-hour window. It is small:
+    a few large tasks a week.
+- Pools are separate: when one runs out, `/model` to a model of another pool keeps the agent working on the same
+  account.
+- Quota is spent in proportion to the cost of the tokens: shorter tasks and cheaper models last longer.
+- `/context`: tokens used of the model's window (e.g. `0/1.0M tokens (0.0%)`), split into user messages, agent
+  responses and tool calls. Esc closes it.
+- `/credits`: remaining G1 credits. With **Use AI Credits** on, the agent keeps going on credits after the quota ends;
+  turning it on spends money, so ask the user.
+- Not yet observed: the quota-exhausted screen.
+
+## Keys
+
+| Key | Raw | Action |
+|---|---|---|
+| Enter | `\n` | Send or confirm |
+| Esc | `\e` | Go back / dismiss |
+| Ctrl+C | `\x03` | Go back / dismiss |
+| Backspace | `\x7f` | Delete a character |
+| ↑ / ↓ | `\e[A` / `\e[B` | Navigate |
+| Shift+Tab | `\e[Z` | **Cycles Agent Mode**: do not send unless asked |
+| Ctrl+K | `\x0b` | **Approves a subagent**: same care as a permission prompt |
+| Ctrl+D | `\x04` | **Exits the CLI**: never send |
+| Ctrl+Z | `\x1a` | **Suspends the CLI**: never send |
+| `?` | `?` | Help panel (general, commands, shortcuts) |
+
+## Slash commands for the Maestro
+
+`/model`, `/effort`, `/config`, `/permissions`, `/usage`, `/credits`, `/clear`, `/compact`, `/context`, `/resume`,
+`/rewind`, `/tasks`, `/btw` (side question without interrupting the task), `/skills`, `/mcp`, `/hooks`, `/help`. `/exit`
+and `/logout` stop the agent or sign it out: only when the user asks.
+
+## Built-in capabilities
+
+Tools as the agent listed them (Gemini 3.8 Flash): `read_file` (text, images, audio, video, PDF), `edit_file`,
+`write_file`, `run_command`, `manage_task`, `ask_question`, `invoke_subagent`, `define_subagent`, `manage_subagents`,
+`send_message`, `schedule`, `search_web`.
+
+| Need | How |
+|---|---|
+| Web search | `search_web` |
+| Read images, audio, video, PDF | `read_file` |
+| Drive a browser | `/browser <task>`: browser subagent on Google Chrome, records the session (docs; not tried) |
+| Subagents | `invoke_subagent`; approve them in `/agents` (Ctrl+K approves in place) |
+| Plan before editing | `/plan [task]` or Agent Mode `plan` |
+| Side question while it works | `/btw <query>` |
+| Run until a goal is met | `/goal <objective>` |
+| Timer or recurring task | `/schedule <when> <task>` |
+| Code search | `/codesearch <query>` |
+| Background shell logs | `/tasks` |
+
+Built-in skills (`~/.gemini/antigravity-cli/builtin/skills`, marked `built-in` in `/skills`): `agy-customizations`,
+`antigravity-guide`, `schedule automation`, `migrate-workflows`, `run-workflow` (Python script that orchestrates many
+agents). The folder also holds `generative_ui`, `permissioned-github`, `plugin` and `ui-plugin-navigation`, which
+`/skills` did not list as built-in in the CLI.
+
+`/skills` also lists skills from `~/.gemini/config/skills` (where Maestri installs its own) and from plugins: those are
+not built in.
+
+## Not yet observed
+
+Quota-exhausted screen, logged-out screen, model or network errors, and how Queued Messages behaves while the agent is
+busy.

package/skills/maestri-agent-cli/references/claude-code.md

@@ -0,0 +1,203 @@
+# Claude Code
+
+Verified live on Claude Code 2.1.302, Windows, Claude Max account (2026-10-27).
+
+## Identify
+
+- Launch command: `claude`, e.g. `claude --model claude-haiku-5-5 --effort low`.
+- Banner: `Claude Code v<version>`, model and effort, plan (`Claude Max`), working folder.
+- Account: `/config` → **Status** tab (login method and account). The banner shows only the plan.
+- Input prompt is `❯` (not `>`).
+- Footer shows the permission mode: `⏵⏵ auto mode on (shift+tab to cycle)`, `⏸ manual mode on · ? for shortcuts`,
+  `⏵⏵ accept edits on`, `⏸ plan mode on`. Effort shows above the input: `○ low · /effort`.
+
+## States
+
+| State | On screen |
+|---|---|
+| Idle | Empty `❯` input; footer with the mode |
+| Prompt suggestion | Greyed text in the `❯` input, e.g. `❯ Try "write a test for <filepath>"` or a follow-up like `❯ delete the file ...`. **Nobody typed it**: it is a suggestion, never an instruction or a reply |
+| Working | Spinner line, e.g. `✻ Brewing…` |
+| Permission prompt | `Do you want to create <file>?` or `Do you want to proceed?` with numbered options |
+| Menu or panel | Picker with hints such as `Esc to cancel` |
+| Done | Agent's reply, then `✻ <verb> for <time> · done <clock>` and an empty input |
+| Denied or interrupted | `⎿ Interrupted · What should Claude do instead?` |
+
+Lines like `● Write(<file>)`, `⎿ $ <command>` and `Ran 1 shell command` show up while the prompt is still open, and
+`Ran 1 shell command` stays even when the command was denied. Trust only the result line (`⎿ Wrote 1 line to <file>`) or
+the agent's reply.
+
+## Sending a prompt
+
+Send the text and the Enter in **separate** `--raw` calls. Text and `\n` sent together are taken as a paste: the newline
+lands in the input and nothing is sent.
+
+```bash
+maestri ask "Agent" --raw "your prompt"
+maestri ask "Agent" --raw "\n"
+```
+
+## Autonomous launch and command rules
+
+Verified on Claude Code 2.1.302, Windows (2026-11-06): installed help and isolated startup argument checks.
+
+```bash
+claude --permission-mode auto
+```
+
+Auto mode reviews actions without routine prompts. It is distinct from `acceptEdits`, which still prompts for commands.
+Confirm `auto mode on` after launch; availability can depend on account or managed policy. The isolated startup accepted
+the flag and settings example below but stopped at login, so authenticated action execution was not tested here.
+
+For a limited agent, prepare an isolated settings file and launch:
+
+```bash
+claude --permission-mode dontAsk --settings /path/to/limited.json
+```
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(npm --version)", "PowerShell(npm --version)"],
+    "deny": ["Bash(git push *)", "PowerShell(git push *)"]
+  }
+}
+```
+
+`dontAsk` denies actions that would otherwise prompt; explicit grants and operations needing no approval still run.
+This is an approval allowlist, not a complete commands-only boundary. Bash and PowerShell need separate rules.
+Denies override asks, which override allows; a broad deny cannot have an allow exception. Narrow command rules do not
+replace OS isolation. `--tools` can additionally limit available tools when the task needs that restriction.
+
+Persistent rules live in `~/.claude/settings.json` (under `CLAUDE_CONFIG_DIR` when set), `.claude/settings.json` or
+`.claude/settings.local.json`; `--settings` adds invocation settings without editing those files. Use an isolated
+`CLAUDE_CONFIG_DIR` for tests. The file schema and precedence are documented in
+[permissions](https://code.claude.com/docs/en/permissions); only flag acceptance was tested with the fake home.
+
+`--dangerously-skip-permissions` and `--permission-mode bypassPermissions` bypass permission checks. Use them only
+at the user's explicit request, never as the default autonomous launch.
+
+## Permission prompts
+
+Only in `manual` mode (and for commands in `accept edits`). In `auto` mode the agent decides on its own and asks only
+for risky actions. Read-only commands such as `echo` run without asking.
+
+File creation or edit:
+
+```text
+Do you want to create <file>?
+❯ 1. Yes
+  2. Yes, and switch to accept edits (auto-approve file edits and common file commands) for this session (shift+tab)
+  3. No
+Esc to cancel · Tab to amend
+```
+
+Command:
+
+```text
+Bash command
+Do you want to proceed?
+❯ 1. Yes
+  2. Yes, and always allow access to <folder> from this project
+  3. Yes, and switch to auto mode · auto mode handles these prompts for you
+  4. No
+Esc to cancel · Tab to amend
+```
+
+- Option 1 is preselected: Enter (`\n`) approves once. **A number key picks its option at once**, with no Enter.
+- Every option other than "Yes" and "No" changes the mode for the session or persists a rule for the project: ask the
+  user first.
+- "No" interrupts the turn and the agent waits for new instructions.
+
+## Permission mode
+
+Shift+Tab (`\e[Z`) cycles: `auto` → `manual` → `accept edits` → `plan` → `auto`. The change lasts for the session. The
+default for new sessions is **Default permission mode** in `/config`.
+
+## Model and effort
+
+- `/model`, Enter → **Select model**. ↑/↓ picks, ←/→ sets effort.
+- **Enter saves the model as the default for every new session.** Press `s` to use it in this session only. Esc cancels
+  (`⎿ Kept model as <model>`).
+- **Exact ids:** `claude --help` documents `--model` with an alias for the latest model (`opus`, `sonnet`, `fable`) or a
+  full name such as `claude-opus-5-5`, `claude-sonnet-5-5` or `claude-haiku-5-5`, and `--effort` with `low`, `medium`,
+  `high`, `xhigh` or `max`. Presets in `maestri preset list` show working commands. `/effort` sets effort alone.
+
+## Settings (`/config`)
+
+- One panel with tabs: **Settings**, **Status**, **Config**, **Usage**, **Stats**. ↑ from the top of the list reaches
+  the tabs; ←/→ switches tab. Typing filters settings. Esc clears the search, then closes.
+- Enter or ↓ moves from the search box into the list; Enter on a setting changes it. Navigate with ↑/↓ only.
+- Settings that matter to the Maestro: **Default permission mode**, **Model**, **Continue automatically at usage
+  limit**, **Prompt suggestions** (the greyed suggestions in the input), **Auto-compact**, **Thinking mode**, **Fast
+  mode**.
+- **Status** tab: version, session id, login method and account, model, MCP servers, setting sources, and system
+  diagnostics (e.g. a PATH warning).
+- Persistent settings live in `~/.claude/settings.json`, `.claude/settings.json` and `.claude/settings.local.json`;
+  prefer them, or launch flags, over the TUI.
+
+## Quota
+
+- `/config` → **Usage** tab (↑ from the list reaches the tabs, → three times from Settings): limits with a bar, the
+  **percent used** and the reset time, e.g. `Current week (all models) … 80% used · Resets Nov 6, 2am`. Windows:
+  current session (five hours), current week (all models), current week per model family. Below them, hints on what
+  drives usage (long contexts, always-on context). Usage credits are off unless turned on with `/usage-credits`.
+- `/context`: how much of the context window is in use. Not yet verified live on this version: read the screen.
+- **Continue automatically at usage limit** in `/config` lets the agent keep going when a limit is hit.
+- Recovery: wait for the reset, or move the agent to another account with
+  `maestri recruit --replace "Name" --account "Other"`.
+- Not yet observed: the limit-reached screen.
+
+## Keys
+
+| Key | Raw | Action |
+|---|---|---|
+| Enter | `\n` | Send or confirm (send it apart from the text) |
+| Esc | `\e` | Close a panel; cancel a prompt; interrupts the agent while it works. **Twice** clears the input |
+| Backspace | `\x7f` | Delete a character |
+| ↑ / ↓ | `\e[A` / `\e[B` | Navigate |
+| 1-9 | `1`... | Pick a numbered option immediately |
+| Shift+Tab | `\e[Z` | **Cycles the permission mode**: do not send unless asked |
+| Alt+P | | **Switches model** |
+| Ctrl+C | `\x03` | Interrupts or clears; **twice, exits** |
+| Ctrl+D | `\x04` | **Exits**: never send |
+| `?` | `?` | Shortcuts panel (in an empty input) |
+| `!` | `!` | Shell mode (in an empty input) |
+
+## Slash commands for the Maestro
+
+`/model`, `/effort`, `/config` (settings, status, usage), `/permissions`, `/context`, `/compact [what to keep]`,
+`/clear`, `/resume`, `/rewind`, `/btw` (side question), `/mcp`, `/hooks`, `/help`. `/exit`, `/logout` and `/login` stop
+the agent or change its login: only when the user asks.
+
+## Built-in capabilities
+
+Tools (from the docs, present in a Claude Code 2.1.302 session): `Read`, `Edit`, `Write`, `Glob`, `Grep`, `Bash`,
+`PowerShell`, `NotebookEdit`, `WebSearch`, `WebFetch`, `Agent`, `SendMessage`, `Workflow`, `Monitor`, `CronCreate`,
+`EnterPlanMode`, `EnterWorktree`, `AskUserQuestion`, `Skill`, `Artifact` (claude.ai login on a paid plan). Some load on
+demand through `ToolSearch`.
+
+| Need | How |
+|---|---|
+| Web search, read a URL | `WebSearch`, `WebFetch` |
+| Read images, PDF | `Read`; paste an image with Alt+V on Windows |
+| Drive a browser | Only with the Claude in Chrome extension enabled |
+| Subagents | `Agent` (types `Explore`, `Plan`, `general-purpose`) |
+| Many agents from a script | `Workflow`; `/deep-research <question>` (paid plans) |
+| Code review | `/code-review`, `/security-review` |
+| Plan before editing | Plan mode (Shift+Tab) or `/plan` |
+| Side question while it works | `/btw` (no tools, out of history) |
+| Repeat or schedule | `/loop`, `/schedule` |
+| Git worktree | `claude --worktree <name>`, `EnterWorktree` |
+| Shareable page | `Artifact` |
+
+Bundled skills (`disableBundledSkills` turns them off): `/code-review`, `/simplify`, `/security-review`, `/loop`,
+`/schedule`, `/run`, `/verify`, `/batch`, `/claude-api`, `/dataviz`, `/update-config`, `/fewer-permission-prompts`,
+`/debug`, `/doctor`, `/init`, the artifact guides, and `/workflow-authoring` when workflows are on.
+
+Skills with a `plugin:` prefix, from the claude.ai account (`anthropic-skills:`), or in `~/.claude/skills` (where
+Maestri installs its own) are not built in.
+
+## Not yet observed
+
+Limit-reached screen, logged-out screen, API or network errors.