kule run
Give an agent a prompt. It works in the task's copy, inside the sandbox, with its network through the task's proxy. Nothing reaches the workspace until you commit.
Synopsis
kule run [OPTIONS] <TASK> <PROMPT>
Description
kule run starts an agent such as Claude Code, Codex or Gemini, hands it
your prompt, and prints what it does until its turn ends. Kule talks to the
agent over the Agent Client Protocol (ACP), the same way an editor would.
What the agent can do:
- Files: it reads and writes the task's copy. It cannot write your real
folder, and it cannot read your credentials (
~/.ssh,~/.aws, …), your own folders (Documents, Desktop, …) or other agents' logins. See The sandbox. - Network: every connection goes through the task's proxy. Package registries and the agent's own model API pass; anything else is judged by the policy. The CLI has nobody to ask, so a connection the policy would put to a person is refused at once. (In the app it waits for your answer.) See Network and questions.
- Your home: what it writes in
~/.zshrc,~/.configand the like is caught in the task's home layer for you to review with kule home, never written to your home on its own. - Secrets: it sees placeholders, never your API keys. See Secrets.
Every tool call the agent makes that changes files becomes a step (see kule steps). When the run ends, Kule prints what changed in the copy and what the policy says about it, so you can go straight to kule commit or kule rollback. You can also run the agent again first: changes pile up in the copy until you decide.
Budgets and limits hold. A run does not start once one of the task's budgets is spent (its own, its group's, or the daily one for every task), or once the task has used up its time. While it runs, the limits on processor, memory, disk, time and idling hold it, as they do in the app.
The agent hears what changed. If kule sync brought the folder's changes into the copy since the agent's last run, or the sandbox refused it something Kule can explain, a short note in Kule's words goes before your prompt, once.
One agent works in a task at a time. To run agents side by side, make more tasks (on the same folder or others).
The agent must be installed and signed in the way it is without Kule:
Claude Code and Codex need Node.js (npx), Gemini its CLI. kule agents
lists which agents can start here and why the others cannot. See
Agents.
Arguments
| Name | Required | Meaning |
|---|---|---|
TASK | yes | The task's full id. See Naming a task. |
PROMPT | yes | What the agent should do. Quote it: one argument. |
Options
| Option | Value | Default | Meaning |
|---|---|---|---|
--agent | name | claude-code | Which agent takes the prompt: claude-code, codex, gemini, or the name of an agent profile you added and approved (see kule agents). |
--home | path | ~/.kule | Kule's home (also KULE_HOME). See global options. |
Examples
Ask Claude Code to fix a test:
kule run 3422f830 "The test in tests/greet.rs fails. Fix it and run cargo test."
Use Codex instead:
kule run 3422f830 --agent codex "Add a --verbose flag to the CLI."
Work on documents, not code:
kule run 40ac70b8 "Sort the notes in this folder into one folder per year. Keep the file names."
Run, check the ruling, and commit only if everything passes on its own:
kule run "$TASK" "Update the README's install section" && kule commit "$TASK"
kule commit exits with 3 and commits nothing if anything waits for your
approval, so this is safe.
Output
While the agent works, a busy line says what it is doing. A run's output looks like this (the agent's words and tools vary):
I'll look at the failing test first.
✓ Read tests/greet.rs → step 1: no file changes
✓ Edit src/main.rs → step 2: src/main.rs
✓ cargo test → step 3: target/debug/app and 41 more
plan: Read the test / Fix greet / Run the tests
The greeting now matches what the test expects, and cargo test passes.
1 file changes: +0 ~1 -0
~ src/main.rs
~ function greet
net: index.crates.io:443 · tunneled (package-registries)
policy: passes on its own
spent: 0.12 USD, 18234 tokens in 1 run
took: 41s
| Line | Meaning |
|---|---|
| plain text | The agent's answer, as it writes it. |
✓ <tool> → step N: <files> | A tool call that went well, the step it became and the files it changed (the first five; kule steps has the rest). ✗ means it failed. |
plan: | The agent's plan, when it shares one. |
· <note> | A note from Kule or the agent, such as a permission it was given. |
N file changes: +a ~m -d | What the copy now holds that the workspace does not: created, modified, deleted. Inside each file, the functions, sections or keys that changed. See kule status. |
git: | What happened to the repository: branch moves, new objects, config or hook changes. See Git. |
net: | Each connection the run made and whether it went through. |
in your home, caught for review | Writes in your home folder, waiting in the home layer. See kule home. |
sandbox: refused … | What the sandbox refused (macOS lists them; on Linux the command just gets an error). |
policy: | The ruling on the changes: passes on its own, waits for approval or denied, with the rule behind each. |
spent: | What the task's runs have cost so far, as the agents reported it, and what is left of its budget. |
took: | How long the run took. |
When the output is not a terminal, every event is a plain line of its own, which is easier to log.
Errors and fixes
| Message | What to do |
|---|---|
kule: no agent <name>; known: claude-code, gemini, codex | Check the name. Add your own agents with kule agents. |
kule: agent <name> cannot run: <why> | The agent is missing, not signed in, or (for your own profiles) not approved yet. Run kule agents to see why. |
kule: task <id> has spent its budget; raise it or turn it off to run again | Raise it with kule budget TASK <amount>, or kule budget TASK off. The message names a group's or the daily budget when that is the one spent. |
kule: the task has used its time: its runs took N minutes together; … | Raise or remove the task's time limit with kule limits. |
kule: an agent is at work in task <id> … | One agent per task. Wait, or make another task. |
kule: <error> (see <home>/tasks/<id>/agent.log) | The agent failed. Its own messages are in agent.log. |
kule: <agent> reported no cost, so the task's budget does not count this run | A warning, not an error: agents signed in with a subscription may report tokens only, and a budget cannot hold what is not reported. |
On some Linux systems no agent runs until you accept weaker isolation; see kule isolation.
In the app
Write the prompt in the Agent panel (Mod+L puts the cursor there), pick the agent under it and press Enter or Run. The app also shows each tool call's output as it streams, lets you answer the agent's questions, and has Stop (Mod+Shift+K). See Live.
See also
- kule exec: run one command in the sandbox instead of an agent.
- kule steps, kule status, kule commit
- Agents, Budgets and limits