astracode-agent 0.1.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,12 +1,13 @@
1
1
  # AstraCode agent CLI
2
2
 
3
- The AstraCode agent without the editor. It runs one task in the current
4
- directory, then exits. Use it from a shell, a CI job or a script.
3
+ The AstraCode agent in your terminal. Run it in a project folder for an
4
+ interactive session, or give it one task with `-p` from a shell, a CI job
5
+ or a script.
5
6
 
6
7
  ```bash
7
8
  curl -fsSL https://astracode.io/install | sh
8
- astracode-agent login
9
- astracode-agent -p "why does the login test fail?"
9
+ astracode-agent # interactive; signs you in the first time
10
+ astracode-agent -p "why does the login test fail?" # one task, then exit
10
11
  ```
11
12
 
12
13
  The installer puts a standalone binary in `~/.local/bin`, with Node built in.
@@ -14,6 +15,12 @@ It works on macOS and Linux, on arm64 and x64. It checks the download's
14
15
  checksum, and on a Mac also checks that AstraCode signed it. To update, run
15
16
  `astracode-agent update`, which runs the same installer for the latest version.
16
17
 
18
+ With Homebrew, on macOS or Linux:
19
+
20
+ ```bash
21
+ brew install vrx-astracode/tap/astracode-agent
22
+ ```
23
+
17
24
  With Node 20 or later you can also install it from npm:
18
25
 
19
26
  ```bash
@@ -46,6 +53,57 @@ export ASTRACODE_API_KEY=ac_live_...
46
53
  A key takes precedence over a saved session. A key can have its own spending
47
54
  limit, and you can revoke it without signing anyone out.
48
55
 
56
+ ## A conversation
57
+
58
+ ```bash
59
+ astracode-agent
60
+ astracode-agent "why does the login test fail?"
61
+ astracode-agent --continue # pick up this folder's last conversation
62
+ astracode-agent --resume # choose an earlier one
63
+ ```
64
+
65
+ On its own, `astracode-agent` opens a conversation with the agent in the
66
+ current folder. A request on the command line is the first message.
67
+
68
+ - **Asking before it acts.** Before an edit or a command it asks: Yes, Yes and
69
+ don't ask again this session, or No and tell it what to do instead.
70
+ **Shift-Tab** cycles three modes: **ask**, **auto** (edits and commands run
71
+ without asking, though risky ones still ask) and **plan** (it reads and
72
+ writes a plan, then offers to build it).
73
+ - **Steering.** **Esc** stops a run and keeps what it has done so far. A
74
+ message typed while it works reaches it at its next step.
75
+ - **Typing.** `\` Enter, Ctrl-J or Option-Enter adds a new line. Up and Down
76
+ go through history, and Ctrl-R searches it. `@` mentions a file, and `/`
77
+ opens the commands. Ctrl-G opens the message in `$EDITOR`, and Ctrl-V
78
+ pastes an image on macOS.
79
+ - **Output.** Replies stream as they arrive. Each tool call is one line and
80
+ each edit is shown as a diff. Ctrl-O shows full tool output, and Ctrl-T
81
+ shows or hides the todo list. The footer shows the mode, the model and how
82
+ much of the context is used.
83
+ - **Shortcuts.** `!command` runs in your shell, and its output goes with your
84
+ next message. `# note` remembers something about this project.
85
+
86
+ Commands:
87
+
88
+ | command | |
89
+ |---|---|
90
+ | `/clear`, `/resume` | start a new conversation, or go back to one |
91
+ | `/undo`, `/rewind` | take back the last message, or go back to before an earlier one, restoring its edits too |
92
+ | `/compact`, `/context` | summarise the conversation to free context, or see how much is used |
93
+ | `/model` | AstraOne: balanced, most capable, or lowest cost |
94
+ | `/plan` | switch to plan mode |
95
+ | `/memory` | what it remembers about the project |
96
+ | `/init` | write an `AGENTS.md` |
97
+ | `/review`, `/diff` | review this branch, or see uncommitted changes |
98
+ | `/tasks`, `/mcp` | background commands and MCP servers |
99
+ | `/export`, `/status`, `/help` | save the conversation, account and model details, all keys |
100
+
101
+ Your own commands and skills from `.astracode/commands` and
102
+ `.astracode/skills` appear in the `/` menu too. The skills that come with the
103
+ editor (infrastructure as code, web and mobile interface design) come with the
104
+ CLI as well, and a skill of yours with the same name replaces one of them. MCP servers go under
105
+ `"mcp.servers"` in `~/.config/astracode/settings.json`.
106
+
49
107
  ## Running a task
50
108
 
51
109
  ```
@@ -81,7 +139,7 @@ changed.
81
139
 
82
140
  - **`text`**: stdout is the agent's final answer, and nothing else.
83
141
  - **`json`**: stdout is one object, with `ok`, `end`, `summary`,
84
- `filesChanged`, `denied`, `steps`, `costUsd` and `durationMs`.
142
+ `filesChanged`, `denied`, `steps` and `durationMs`.
85
143
  - **`stream-json`**: one JSON object per line, one for each agent event
86
144
  (tool calls, tool results, text, todos), then the same result object.
87
145
 
@@ -112,7 +170,50 @@ apology in the summary.
112
170
  Let the agent make the edits, and let the workflow's own steps commit, push and
113
171
  comment. The agent refuses `git push` under `auto` for that reason.
114
172
 
115
- ## What is different from the editor
173
+ ## In Zed or a JetBrains IDE
174
+
175
+ `astracode-agent acp` speaks the [Agent Client Protocol](https://agentclientprotocol.com),
176
+ so editors that run external agents can use AstraCode as their agent. You sign
177
+ in the same way as on the command line, and usage is billed to your AstraCode
178
+ account.
179
+
180
+ **Zed**: add this to `settings.json`, then pick AstraCode in the agent panel:
181
+
182
+ ```json
183
+ {
184
+ "agent_servers": {
185
+ "AstraCode": {
186
+ "type": "custom",
187
+ "command": "astracode-agent",
188
+ "args": ["acp"]
189
+ }
190
+ }
191
+ }
192
+ ```
193
+
194
+ **JetBrains**: in the AI Chat tool window, choose **Add Custom Agent**, and put
195
+ this in the `~/.jetbrains/acp.json` file it opens:
196
+
197
+ ```json
198
+ {
199
+ "agent_servers": {
200
+ "AstraCode": {
201
+ "command": "/Users/you/.local/bin/astracode-agent",
202
+ "args": ["acp"]
203
+ }
204
+ }
205
+ }
206
+ ```
207
+
208
+ Use the full path that `which astracode-agent` prints. If you are not signed in
209
+ yet, the editor offers to sign you in the first time you use AstraCode.
210
+
211
+ The editor shows each edit as a diff and asks before the agent changes a file
212
+ or runs a command. **Always allow** applies to that tool for the rest of the
213
+ session. Risky commands and requests to other machines are asked about every
214
+ time.
215
+
216
+
116
217
 
117
218
  These are not available without an editor:
118
219