Scripts and CI
Run one task with -p: permissions, trust, output formats, JSON fields, exit codes, undo, GitHub Actions and progress reporting.
On this page
- Options
- Permissions
- Trust
- Output
- text
- json
- stream-json
- Exit codes
- Undo a run
- In GitHub Actions
- Reporting progress
- If something goes wrong
astracode-agent -p runs one task and exits. Nobody is there to approve anything, so what the agent may do is decided up front with --permissions, and every refused action is listed in the result.
Terminal
astracode-agent -p "fix the failing test in tests/test_billing.py" --permissions auto
git diff | astracode-agent -p - --output-format json # the task from stdin
Options
| Option | Default | What it does |
|---|---|---|
-p, --print <prompt> | The task. - reads it from stdin. | |
--mode agent|plan | agent | agent makes the change; plan only writes a plan. |
--permissions read-only|auto|full | read-only | What the agent may do (below). |
--output-format text|json|stream-json | text | The final answer, one result object, or one event per line. |
--max-steps <n> | 150 | The step limit for the run. |
--cwd <dir> | the current folder | The workspace. |
--agents <json or file> | Agent definitions for this run, in Claude Code's shape. They win over .astracode/agents and .claude/agents. | |
--agent <name> | Run the whole task as that agent: its prompt, tools and model tier. | |
--allow-agent-mcp | off | Let the project's agent files start the MCP servers they declare, for this run only. |
--report-to <url> | Post the run's progress as it goes (below). | |
--trust | Accepted and changes nothing: a -p run already trusts its folder. | |
-v, --verbose | off | The agent's own log, on stderr. |
--continue and --resume open a conversation, so they are refused with -p. An empty prompt on stdin is refused with exit code 2.
Permissions
| Level | What the agent may do |
|---|---|
read-only (default) | Read, search and answer. Every edit and command is refused. |
auto | Edit files and run commands. Still refused: a command the risk check flags (such as git push or rm -rf outside the project), a request off this machine, and saving a memory: the things the editor confirms even when it never asks. |
full | Those too. |
In text mode, refusals are listed on stderr after the answer: N action(s) denied under --permissions auto: and one line each. In JSON they are in denied. A CI log therefore says why nothing changed.
Trust
A -p run trusts the folder it runs in: you chose the folder, and --permissions decides what the run may do. The project's rules, hooks, skills, commands and agents all load. A conversation, acp and review are different; see Workspace trust. -p starts no MCP servers from your settings file, and a project's agent files start theirs only with --allow-agent-mcp; your own agent files under ~ start theirs.
Output
text
The agent's final answer on stdout. Reports from background agents it never read follow, each headed [background agent <id> (<type>) "<title>" <state>]. On stderr: to undo this run: astracode-agent undo <runId> when it changed something, and the refused actions.
json
One object when the run ends:
--output-format json
{
"type": "result",
"ok": true,
"end": "finished",
"summary": "Fixed the rounding in invoice totals; the test passes.",
"filesChanged": [{ "path": "src/billing.py", "created": false, "added": 3, "removed": 1 }],
"denied": [{ "description": "run git push", "warning": "..." }],
"steps": 14,
"planSlug": null,
"durationMs": 48210,
"tasks": [],
"runId": "r-20261114-1a2b"
}
| Field | Meaning |
|---|---|
type | Always "result". |
ok | true when the exit code is 0. |
end | How it ended: finished, stopped, looped, ceiling (the step limit) or errored. |
summary | The final answer. |
filesChanged | Each file: path, created, lines added and removed. |
denied | Each refused action: description, and warning when there was one. |
steps | Steps taken. |
planSlug | The plan written, in --mode plan. |
durationMs | How long it took. |
tasks | Every background task: its id, kind, title, state, start and end, and for an agent its type, steps, files changed and report. |
runId | Present only when checkpoints recorded changes; pass it to undo. |
If the run fails before it can produce a result, the object is just {"type": "result", "ok": false, "error": "..."}.
stream-json
One JSON object per line as the run goes: every event the agent emits except the streaming text and thinking fragments. Among them toolCall, toolResult (with a fileChange for edits), text, thinking, progress, todos, plan, context, compacted, and agentStarted, agentProgress and agentEnded for subagents. Any event may carry agentId and parentAgentId. A refusal is {"type": "denied", ...}, and the last line is the result object above.
Exit codes
| Code | Meaning |
|---|---|
| 0 | The agent finished. |
| 1 | It did not finish (the step limit, a loop, an error), or the gateway refused the request. |
| 2 | A usage error; not signed in; --cwd is not a folder; a bad --agents or --agent; or an empty prompt on stdin. |
| 130 | Interrupted. A second Ctrl-C exits at once. |
A run that stopped short fails the job: it does not report success with an apology in the summary. Background agents are waited for before the CLI exits.
Undo a run
Terminal
astracode-agent undo # the last run in this folder not yet undone
astracode-agent undo --list # the last ten runs, newest first
astracode-agent undo <run> # that one
astracode-agent undo --restore <id> # take an undo back
Every run that may change files, in a conversation, with -p or over acp, takes a checkpoint before each edit and each command, kept outside the project in the CLI's config folder. undo puts back what the run changed, including what its commands created, deleted or rewrote, and lists each file it restored, removed or reverted. It leaves alone any file changed again since, and says Left alone, changed since: with their names. It ends with the --restore command that takes the undo itself back. undo needs no sign-in, accepts --cwd, and needs git on your PATH. Read-only, plan and review runs change nothing, so they have nothing to undo.
In GitHub Actions
- Create an API key on your dashboard under API & SSH keys, and add it to the repository as a secret named
ASTRACODE_API_KEY. - Add a step that installs the CLI, and one that runs the task with that secret in its environment.
- Let the workflow's own steps commit, push and comment. The agent refuses
git pushunderautofor exactly that reason.
.github/workflows/fix.yml
- uses: actions/checkout@v4
- run: curl -fsSL https://astracode.io/install | sh
- run: ~/.local/bin/astracode-agent -p "Fix the failing test in tests/test_billing.py" --permissions auto --output-format json > result.json
env:
ASTRACODE_API_KEY: ${{ secrets.ASTRACODE_API_KEY }}
No update notice is printed when CI is set. To have AstraCode run the agent in your repository's Actions for you, from the editor or from another app, see Remote agents in GitHub Actions. To review pull requests, see Reviewing a branch.
Reporting progress
--report-to <url> posts the run's progress to <url>/events as it goes, one small JSON event per request, {seq, type, data}, with the run's credential as the bearer token. The types are started, each step, each tool by name, the final report (up to 20,000 characters), and ended with the outcome. Never a tool's input or output, a file, a path or a command.
- The URL must be
https://, orhttp://only to this machine, and must not carry a username, password, query or fragment. - Each event is tried up to four times with growing waits. After three in a row are dropped, the endpoint is taken to be down and only the report and the end are still tried. At most 1,000 events are sent; at exit the CLI waits up to 10 seconds for what is queued.
- Delivery never slows or fails the run, and the exit code is the agent's whatever the endpoint did.
- It is how a remote agent reports to its card in the editor.
If something goes wrong
- Exit 2 with Not signed in: set
ASTRACODE_API_KEYin the step'senv, not only as a repository secret. - Nothing changed and exit 0: the default is
read-only; pass--permissions auto. - ERROR: content search is unavailable (ripgrep not found in this build).: install ripgrep on the runner.
- No `runId` in the result: git is not on PATH, so no checkpoints were taken.
- Everything else: CLI problems.
← The conversation Reviewing a branch →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems