Commands & the terminal
How the agent runs commands that yield and keep running, and your own terminal beside it.
See it in action on the Terminal page.
How the agent runs a command
The agent's shell tool runs a command and waits up to yield_time_ms for it. The wait is 10 seconds by default, and between 250 ms and 30 s (10–30 s on Windows). Then the tool returns one of these:
- The output so far, and the exit code if the command finished.
- A session id if the command is still running. The command keeps running in the background.
With a session id, the agent uses write_stdin to do one of these:
- Poll for new output. Sending nothing waits 5 s to 5 min for more.
- Type into the command, when the command started with a terminal (
tty). - Send Ctrl-C.
Without a terminal, a session takes only Ctrl-C.
So a dev server, a watcher or a long test run doesn't block the turn. The agent starts it, continues, and checks it again later. KodaCode refuses backgrounding with &, nohup, setsid or disown, because the session id already does that.
Each command says what it does: read, add, edit, delete, download, install, build or test. Approvals use this to decide whether the command asks.
Running commands in the session
The prompt box's dock lists commands that still run. Each has a Stop button. Stop all ("Stop every background command in this conversation") stops them all. When you interrupt a turn with Esc, its commands keep running. Stop them here. The dock shows a command's end after its turn.
Subagents that started commands stay open until the main agent closes them. Closing a subagent stops its commands. A goal can poll a running command. While one runs, the goal can't merge and you can't discard it.
Long output
KodaCode keeps the head and tail of the output. The transcript row's Show all N lines loads the rest. KodaCode compresses output from common tools (test runners, linters, builds) before the model reads it. /metrics shows the savings under Shell output savings.
Which shell
On this computer, commands run in sh on macOS and Linux. On Windows they run in Git Bash from Git for Windows. Choose another shell in Permissions & sandbox → Shell for commands. KodaCode test-runs it before it saves the choice. Projects in Docker or Podman use the container's shell.
Your terminal
Open the terminal panel with ⌘J or ⌃`. You can:
- Choose Host shell, Project container or Goal container.
- Open more terminals with New terminal.
- Choose Dock to the bottom or Float over Koda.
Inside the terminal, KodaCode captures only the terminal toggle, so your shell keeps its Ctrl keys.