# AKK Operator Guide This guide is the day-to-day command and reliability reference for controlling Codex or Claude Code processes that are already running in tmux or local Herdr. Start with the [five-minute tmux guide](quickstart-tmux.md), the [Herdr guide](quickstart-herdr.md), or one of the first-party Host guides for [Pi](../connectors/pi/README.md) and [DeepSeek Harness](../connectors/deepseek-harness/README.md). AKK never launches a hidden replacement coding agent. The terminal remains visible and directly usable by a human while OpenClaw, Pi, DeepSeek Harness, or another compatible controller Host observes and controls it through AKK. ## Command reference Direct slash commands are available in every first-party Host integration: | Command | Purpose | | --- | --- | | `/akk ` | Send a task when AKK can prove one unique send-ready terminal. | | `/akk : ` | Send to the exact selector returned by the current list. | | `/akk list` | Discover live terminals, managed work, Watches, and safe actions. | | `/akk watch ` | Observe one exact terminal without changing it. | | `/akk unwatch ` | Stop one read-only Watch. | | `/akk threads ` | List resumable native threads for one terminal. | | `/akk models ` | Inspect the current native model and reasoning choices for one exact idle terminal. | | `/akk repair-model-control ` | Clear only an exact advertised stale Codex 0.154 `/model` Composer surface or open native picker and prove an empty Composer. | | `/akk set-model

` | Select one exact tuple from the immediately preceding model catalog. | | `/akk new-thread ` | Start a clean native coding-agent thread. | | `/akk clear-thread ` | Alias for the same clean-thread lifecycle action. | | `/akk resume-thread [thread]` | Resume one exact native thread. | | `/akk status ` | Inspect a managed Turn or Terminal Watch. | | `/akk respond ` | Answer a question inside the same managed Turn. | | `/akk cancel ` | Interrupt one exact active managed Turn. | `/akk list` is terminal-first. Each live pane appears once in `terminals[]`. The optional `managed.current_turn` is active work; `managed.recent_turn` is retained history and does not occupy the terminal. Attention-needed records whose pane is unavailable appear in `unavailable_managed_turns[]`. Terminal status has three independent evidence axes. `screen_state` describes the bounded live TUI (`idle`, `working`, `awaiting_approval`, or `unknown`); `native_identity_state` describes foreground native-session resolution (`resolved`, `ambiguous`, `verified_absent`, or `unavailable`); and `durable_activity_state` describes exact rollout/transcript task evidence (`idle`, `working`, or `unknown`). The legacy `activity_state` remains a conservative compatibility projection and can therefore be `unknown` while `screen_state` is `idle`. These fields are diagnostic; `available_actions` remains the authority for tool calls. Human-facing selectors are a slash-command convenience. Structured tools use semantic identities: `session_id` for strict continuation, `terminal_id` for the currently verified physical terminal, `turn_id` for one managed dispatch, `watch_id` for read-only observation, and `native_thread_id` for resume. A `session_exact` action targets the continuing native context; a `terminal_follow_current` action targets the current verified context in the pane. Except for user-intent-first Watch, always use the exact action and prefilled semantic IDs from a fresh list. ## Reliable Send The v28 `action_contracts` expose model-facing semantic IDs only. The trusted adapter privately derives and revalidates terminal, process, binding, native thread, composer, approval, handoff, revision, and compare-and-swap evidence. Callers never supply those opaque fences. A managed Send verifies one terminal and native context, creates one Turn, proves exact request acceptance, monitors that Turn, and returns completion or attention callbacks to the initiating Host. A completed `turn_id` is history, not a destination for another task. A question inside a live Turn uses the advertised `respond` action with that Turn's `turn_id`. Native questionnaire prompts use `respond_interaction`, not ordinary `respond`. For a supported pending step, the managed monitor sends an `interaction_required` callback to wake the owning controller conversation. That callback is notification only and carries no private response authority: first obtain the current managed Turn's `interaction_state` from Status in the same controller conversation, show that exact step to the user, and submit only its advertised semantic question/option IDs or bounded typed text. One call resolves one current step; the resumed monitor notifies the next supported step when it appears. Status remains the manual refresh fallback. Never respond to `manual_required`, expired, changed, secret-bearing, or uncertain state. The user-priority `terminal_user_explicit` path requires one exact live physical terminal/process and a scanned, non-blocked approval state. Broken AKK Turn, Session, transfer, transition, ledger, or Store state cannot veto the user's explicit Send. Codex physical fallback does not depend on Composer visibility, stability, or exactness: it sends `C-u` once, injects the new request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation cannot veto Enter. Claude Code fallback remains exact-empty-only. AKK first takes the managed path where its stronger pre-input requirements hold. Otherwise it may deliver unmanaged work once and best-effort attaches a Terminal Watch that provides the completion callback. Watch preparation or persistence failure is reported but never vetoes, revokes, or retries the successful Send. If terminal delivery or native acceptance is uncertain, AKK does not retry automatically; inspect Status, the exact pane, or the returned Watch instead. On first attach, the target terminal must be explicitly named by the user. AKK never guesses which already-running pane should receive the task. An omitted target is allowed only when AKK can prove one unique eligible terminal. ### Codex candidate attribution The human-priority Codex path also covers a status-card-only Session, a quiescent managed pane whose foreground rollout cannot be selected, and a supported manual `/clear` whose new logical thread appears before its rollout materializes. The complete exact inventory domain binds the provider terminal, PID and process birth, workspace and canonical endpoint, and every open rollout's UUID, descriptor, device, inode, canonical path, and pre-submit byte offset. A `/clear` resume hint is advisory only, never routing or acceptance authority. Under the terminal lock, AKK isolates the predecessor, creates a separate zero-UUID provisional Session and Turn, sends the real request once, and binds only the single rollout that proves exact request acceptance. A rollout-backed Codex row therefore advertises `terminal_follow_current`, not `session_exact`; a cached or direct `session_exact` attempt rejects before task text and never downgrades itself. Only released predecessor Turn history from an earlier binding epoch is excluded from current authority. Use only the freshly listed semantic-ID action. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. This provisional path can still work in a narrow pane because it binds from acceptance rather than automating native `/status`. ### Explicit Codex foreground identification When a recent `/clear` has not yet materialized a rollout, or several open rollouts make `native_identity_state="ambiguous"`, a fresh List may advertise two Codex-only actions. `identify_foreground({terminal_id})` holds the exact terminal lock and sends the closed `/status` probe exactly once, but performs no Store mutation and creates no Session, Turn, receipt, monitor, or callback. The returned proof expires after 30 seconds and is diagnostic only: it cannot authorize Send, approval, questionnaire response, lifecycle input, or a later binding after the lock is released. `identify_and_send({terminal_id,request})` is the actionable atomic form. It keeps one terminal lock from foreground identification through the one task dispatch. The status UUID is provisional; only one rollout that later accepts the exact request can become durable Session/Turn identity. A changed or uncertain probe boundary stops before the task and is not retried automatically. This optional enhancement is not a prerequisite for ordinary human Send: ordinary Send retains its user-priority behavior and does not run `/status`. Normal List and Status are also observation-only and never probe. ## Terminal Watch Watch is read-only and user-intent-first: ```text /akk list /akk watch /akk status /akk unwatch ``` The fresh list is the safest way to copy a complete `terminal_id`, but missing Watch advertisement, coding-agent version uncertainty, unusable task artifacts, or existing managed ownership are warnings rather than authorization vetoes. Watch fails only when the exact terminal/process cannot be identified, neither an exact task anchor nor a read-only terminal-activity path exists, or the durable Watch record cannot be created. An exact provider anchor produces `watch_mode="exact_task"` and `confidence="exact"`. Without one, AKK can use `watch_mode="terminal_activity"` and `confidence="best_effort"`: it must first observe working or approval activity and then stable idle. That callback proves only that the observed activity became idle, not that one uniquely identified task succeeded, and it contains no exact-task completion text. A Watch sends no terminal input and does not adopt, reserve, block, interrupt, approve, or own the selected task. Manual-Watch approval events are notification-only and never participate in auto-approval. Durable Watch state, notification identities, and callback outboxes make restart recovery idempotent. A managed Turn monitor remains preferable when exact Turn attribution already exists. ## Sessions, Turns, and native threads AKK keeps these identities separate: ```text tmux or Herdr terminal / verified process incarnation ├─ native Codex or Claude Code session │ └─ AKK Session (session_id) │ ├─ Turn (turn_id) │ └─ Turn (turn_id) └─ Terminal Watch (watch_id) ``` New and resume are native lifecycle transitions. They create or activate an AKK Session but create no Turn. Run `/akk threads ` to get the current candidates. The output includes deterministic numbers, collision-safe display-only short IDs, and each complete native thread UUID. The number and short-ID resume forms belong only to that displayed snapshot; neither is a durable identity or model authority. They expire after five minutes and after terminal, process, workspace, binding, candidate-set, or relevant action changes. `previous` is advertised only when the current Session's latest committed transition and fresh discovery prove exactly one resumable source. If `previous` is present, use only its exact prefilled semantic-ID action for a natural-language “刚才那个” request. Never substitute the newest terminal row. Do not ask AKK to send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, `/btw`, Claude `/branch`, or another first-line native slash command as an ordinary task. Use the advertised lifecycle, native-inspection, or Codex foreground-identification action, express the outcome in natural language, or type an unsupported command directly in the TUI. AKK revalidates the entire candidate snapshot before terminal input; candidate-set changes fail closed. A replaced or changed transcript/rollout cannot be resumed under stale metadata. ## Safe model control Model control is a two-step, current-snapshot operation. Start from a fresh `/akk list`, copy one complete `terminal_id` whose row advertises `available_actions.model_options`, then run: ```text /akk models /akk set-model

``` The first command opens and closes the agent's native model UI as one bounded inspection. It returns the effective model, the semantic model IDs currently available to that account and runtime, and each model's available reasoning efforts. This is dynamic authority, not a static AKK allowlist: copy one exact model ID and one exact reasoning value from that result. Both values are required; an omitted, invented, or unadvertised effort fails before native model-selection input. The structured postcondition remains authoritative about the effective tuple. The matching OpenClaw tools are `agent_knock_knock_model_options({terminal_id})` and `agent_knock_knock_set_model({terminal_id,model,reasoning_effort})`. The options result and its private physical-terminal/catalog authority belong to the same controller conversation and are consumed by one set-model attempt. Relist after any pane, process, catalog, or UI change, or after any failed attempt. Neither tool accepts a slash command, raw key, menu index, display label, scope override, token, or fingerprint. If a failed Codex 0.154 attempt leaves an exact profiled `/model` popup or an exact bare `/model` Composer, List may advertise both `model_options({terminal_id})` and `repair_model_control({terminal_id})`. The former uses separate residual-bound authority to continue that exact slash command into read-only catalog discovery without retyping it. The latter is the cleanup-only alternative; its equivalent human command is `/akk repair-model-control `. It accepts only the terminal ID and privately revalidates the pane, process, residue, approval state, and absence of an active Turn before every reversible cleanup input. It never presses Enter, selects a model, submits a task, or handles an approval or questionnaire. Success requires an exactly empty Composer. An uncertain continuation or repair is not retryable. If the exact native model picker is already open, List projects the terminal as non-idle and advertises only `repair_model_control`. That repair may dismiss the exact picker but never receives authority to press Enter. Both steps use explicit current-snapshot authority for the same exact physical terminal and coding-agent process. Codex 0.154 may use either one exact current native Session or a verified-zero-rollout pane, and the Codex-only `identify_foreground` diagnostic is not a prerequisite. Claude Code still requires one exact current native Session. The pane must remain safely idle with an exactly empty Composer, except for the exact Codex residual continuation described above. An active Turn, working agent, approval, questionnaire or editor, read-only viewer, non-empty Composer, ambiguous or multi-rollout Codex identity, stale physical snapshot, unsupported version, or changed catalog fails closed with no model-selection input. The private multi-step native sequence revalidates each frame and must return to the main Composer without submitting a task or answering a prompt. Provider scope is explicit in both results: - Codex reports `scope="current_and_new_sessions"`. Its native model flow changes this session and persists the selected model as the default for future Codex sessions. Ordinary reasoning efforts through `max` are also persisted. Codex treats `ultra` specially: it is effective only in the current session, while the future-session effort falls back to a non-Ultra value. The scope label therefore does not claim that Ultra itself persists. These are intentional, visible side effects of the approved native operation; AKK does not edit `~/.codex/config.toml` directly or restore it afterward. - Claude Code reports `scope="current_session"`. Its native session-only path changes the open session and leaves new-session defaults unchanged. A successful result is `changed` or `already_effective` and reports the current session under `effective`, the future Codex defaults under `new_session_defaults`, and whether they changed under `defaults_changed`. For an Ultra request, expect `effective.reasoning_effort="ultra"` and only the persisted model in `new_session_defaults`. The native TUI does not expose the exact non-Ultra effort it chooses for new sessions, so AKK omits that field rather than guessing; never infer that Ultra became a future default from `scope="current_and_new_sessions"` alone. `outcome="uncertain"` means native input may have taken effect but AKK could not prove the final state. It carries `do_not_retry=true`: inspect the shared pane, then obtain a new model catalog before any deliberate new attempt. Model control creates no AKK Turn and never approves, answers, or submits coding work. ## AKK Status and native inspection `/akk status` reads AKK state and a bounded terminal screen. It does not run the coding agent's `/status`. Native inspection is a separate, closed action: `native_inspect({terminal_id,inspection:"status"})`. It accepts no arbitrary command and creates no AKK Turn, Session, receipt, monitor, or callback. Native inspection and foreground identification are different contracts. `native_inspect` inspects an already attributable native context. The explicit Codex-only `identify_foreground` action is available for an otherwise safe but ambiguous foreground and returns only the 30-second non-authorizing diagnostic described above. `identify_and_send` consumes its observation without releasing the terminal lock; callers must never cache a standalone proof and use it as authority for a later action. Codex native `/status` inspection requires an exact viewport of at least 80 columns so the complete UUID can be proven. An ordinary terminal-scoped task does not run `/status` and does not fail merely because the pane is narrow; it can bind from exact native acceptance afterward. Claude inspection must prove, parse, and dismiss one fresh Status panel and return to the same idle composer. Other complete `x.y.z` agent versions remain callable with a compatibility warning; incompatible runtime behavior fails or becomes uncertain rather than being blocked by a version allowlist. ## Approval boundaries Approval always requires the current exact prompt and explicit human intent. Managed approval uses `approve({turn_id})`; terminal-scoped manual Codex approval uses `approve({terminal_id})` when the current list advertises it. On an unmanaged raw-terminal row, that action is prefilled with its exact `terminal_id`; never construct or guess the target. The private approval fence is prompt-scoped. It binds the adapter-isolated exact unredacted approval region, terminal/process identity, decision keys, prompt kind, working directory, reason, and request evidence. The whole-screen digest and redacted excerpt are diagnostic only: output outside the approval region may keep scrolling without invalidating the same prompt. Any change inside the exact region—including a command or an otherwise identically redacted secret—rejects and sends zero approval keys. Terminal-scoped approval leaves Session and Turn identity unchanged, is never available to auto-approve, and must not be retried blindly after an uncertain transport result. Unsupported, stale, changed, ambiguous, or ownership-drifted prompts remain for the human to resolve in the coding-agent TUI. OpenClaw's optional exact-command auto-approval policy is documented separately in [OpenClaw operations](openclaw-operations.md#automatic-approval). ## Recovery and advanced controls Use fresh List and Status before every recovery action. Advanced slash commands appear only when the matching state makes them meaningful: | Command | Use | | --- | --- | | `/akk doctor` | Diagnose installation, Host, terminal, and coding-agent readiness. | | `/akk models ` | Inspect one idle pane's exact native model and reasoning catalog. | | `/akk repair-model-control ` | Clear one exact List-advertised stale Codex `/model` surface; never submit it. | | `/akk set-model ` | Consume that catalog once; Codex reports current and future defaults separately (Ultra stays current-only), while Claude Code is session-only. | | `/akk approve ` | Approve one current prompt after explicit review. | | `/akk renew ` | Restart monitoring for one still-live stalled Turn without terminal input. | | `/akk retry-callback ` | Retry one persisted failed callback with its original identity. | | `/akk close ` | Release AKK management without terminal input or stopping the coding agent. | Explicit Close is the user's management escape hatch. It has priority over broken deferred-transfer or handoff state, closes the selected Turn first, and then best-effort releases only linked AKK metadata. Refresh List afterward; if the agent is still working, a new read-only Watch can observe it. An uncertain terminal mutation is not a retry instruction. Do not resend, approve, cancel, or repeat Enter blindly. Inspect the exact pane and durable Status, then use only the action currently advertised by AKK. ## Structured tool surface The OpenClaw plugin and Host Adapter register the ordered semantic tool catalog. Pi and DeepSeek Harness verify the Host Adapter capability handshake against their actual registrations, so the tool count and names are derived from that catalog rather than maintained as connector constants. The current catalog includes list, watch, unwatch, list resumable threads, native inspect, model options, repair model control, set model, identify foreground, identify and send, new thread, reconcile binding, resume thread, status, send, respond, typed native interaction response, approve, renew, retry callback, cancel, and close. Model-facing mutations contain semantic IDs and user content only. Connector prereleases that pin an earlier AKK runtime retain the tool surface documented by that connector release. Selectors, pane routes, draft text, fingerprints, tokens, revisions, candidate fences, and binding generations stay inside the trusted Host adapter. For the full lifecycle, callback, identity, handoff, and persistence contract, see the [Terminal Handoff Protocol](bidirectional-agent-protocol.md). For configuration and recovery specific to OpenClaw, see [OpenClaw Operations](openclaw-operations.md).