astracode-agent 0.4.0 → 0.5.0
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 +81 -5
- package/dist/astracode-agent.cjs +9767 -4444
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -98,6 +98,7 @@ Commands:
|
|
|
98
98
|
| `/tasks` | background agents, commands and monitors: `/tasks <id>` shows one's output or report, `/tasks stop <id>`, `/tasks stop-all` |
|
|
99
99
|
| `/agents` | the agents it can start: built-in, the project's, yours and `--agents`, with each file and what it shadows |
|
|
100
100
|
| `/mcp` | MCP servers and their tools |
|
|
101
|
+
| `/plugin` | in the line session: list, install and manage plugins, as `astracode-agent plugin` does (below) |
|
|
101
102
|
| `/export`, `/status`, `/help` | save the conversation, account and model details, all keys |
|
|
102
103
|
|
|
103
104
|
### Subagents and background tasks
|
|
@@ -141,8 +142,23 @@ Fields: `description` and `prompt` (required), `tools`, `disallowedTools`
|
|
|
141
142
|
`mcpServers` (names of configured servers), `hooks`, `background`,
|
|
142
143
|
`isolation: "worktree"`, `effort`, `color`, `memory`.
|
|
143
144
|
|
|
145
|
+
An agent file can declare its own MCP servers (`mcpServers:` with a
|
|
146
|
+
`command` or a `url`), started with the agent and stopped when it ends. Those
|
|
147
|
+
in your own files (`~/.astracode/agents`, `~/.claude/agents`) start. A
|
|
148
|
+
project's file is the repository's to write, so in a conversation its server
|
|
149
|
+
starts only in a folder you said you trust, after you have been shown exactly
|
|
150
|
+
what runs and said yes (remembered on this machine, and asked again if the
|
|
151
|
+
definition changes). With `-p` and `acp` nobody can be asked: they start only
|
|
152
|
+
with `--allow-agent-mcp`, for that run. Servers get exactly the environment
|
|
153
|
+
the file gives them.
|
|
154
|
+
|
|
155
|
+
The shared task list the agents work from is kept with the conversation, so
|
|
156
|
+
`--continue` and `/resume` bring it back.
|
|
157
|
+
|
|
144
158
|
**`--agent <name>`** runs the whole session as one agent: its prompt, its
|
|
145
|
-
tools and its model tier. It works with or without `-p`.
|
|
159
|
+
tools and its model tier. It works with or without `-p`. If its tools say
|
|
160
|
+
`Agent(explore, plan)`, those are the only agents the session can start; any
|
|
161
|
+
other is refused by name.
|
|
146
162
|
|
|
147
163
|
Your own commands and skills from `.astracode/commands` and
|
|
148
164
|
`.astracode/skills` appear in the `/` menu too. The skills that come with the
|
|
@@ -166,6 +182,8 @@ astracode-agent -p "<prompt>" [options]
|
|
|
166
182
|
| `--cwd <dir>` | The workspace. The default is the current directory. |
|
|
167
183
|
| `--agents <json\|file>` | Agent definitions for this run. See [Subagents](#subagents-and-background-tasks). |
|
|
168
184
|
| `--agent <name>` | Run as that agent: its prompt, tools and model. |
|
|
185
|
+
| `--allow-agent-mcp` | Start the MCP servers the project's agent files declare. See [Subagents](#subagents-and-background-tasks). |
|
|
186
|
+
| `--trust` | Accepted and changes nothing: a `-p` run trusts the folder it runs in, as Claude Code's `-p` does. A conversation, `acp` and `review` take it too, and there it matters: without it (or `ASTRACODE_TRUST=1`, or a folder you trusted once, or `/trust` in a conversation) the agent changes no file and runs no command, and the project's rules, hooks, skills, commands and agents are not loaded. `review` stays untrusted unless told, because a fork's pull request reaches it. |
|
|
169
187
|
| `--report-to <url>` | Post the run's progress to `<url>/events` as it goes. See [Reporting progress](#reporting-progress). |
|
|
170
188
|
| `-v, --verbose` | Prints the agent's log on stderr. |
|
|
171
189
|
|
|
@@ -263,9 +281,51 @@ instead of on your machine (`isolation: remote`) and come back as a pull
|
|
|
263
281
|
request. "AstraCode: Enable remote agents for this repository" writes
|
|
264
282
|
`.github/workflows/astracode-agent.yml` for you to review and commit; it runs
|
|
265
283
|
this CLI, at a pinned version, with `--report-to` the gateway, so the agent's
|
|
266
|
-
card in the editor follows each step. It needs
|
|
267
|
-
|
|
268
|
-
|
|
284
|
+
card in the editor follows each step. It needs Actions allowed to open pull
|
|
285
|
+
requests, and no secret: each run signs in with the identity token GitHub gives
|
|
286
|
+
the job. A repository secret `ASTRACODE_TOKEN` (an API key with the "Run agents"
|
|
287
|
+
scope), if set, is used instead. See [Remote agents](https://astracode.io/docs/agent/remote-agents/).
|
|
288
|
+
|
|
289
|
+
## Plugins
|
|
290
|
+
|
|
291
|
+
Plugins written for Claude Code or Cursor, or in the open Agent Plugins
|
|
292
|
+
format, install from marketplaces you add: a GitHub repository, any git url,
|
|
293
|
+
or a folder on your machine. A plugin brings skills, commands, agents, rules,
|
|
294
|
+
hooks and MCP servers, and the CLI and the editor share what is installed.
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
astracode-agent plugin marketplace add anthropics/claude-code
|
|
298
|
+
astracode-agent plugin list --available
|
|
299
|
+
astracode-agent plugin install hookify@claude-code-plugins
|
|
300
|
+
astracode-agent plugin list
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
| command | |
|
|
304
|
+
|---|---|
|
|
305
|
+
| `plugin marketplace add <owner/repo[#ref] \| git url \| folder>` | add a marketplace; its name is the one its `marketplace.json` gives |
|
|
306
|
+
| `plugin marketplace remove\|update <name>`, `plugin marketplace list` | |
|
|
307
|
+
| `plugin list [--available] [--json]` | what is installed and what each one contributes, or what your marketplaces offer |
|
|
308
|
+
| `plugin install <name[@marketplace]> [--scope user\|project] [--yes]` | install; `project` applies only in this folder, once it is trusted |
|
|
309
|
+
| `plugin update <name@marketplace> [--yes]` | fetch its newest commit |
|
|
310
|
+
| `plugin uninstall\|enable\|disable <name@marketplace>` | |
|
|
311
|
+
| `plugin approve <name@marketplace> [--yes]` | allow the hooks and servers of a plugin installed for you, such as one your organisation requires |
|
|
312
|
+
| `plugin config <name@marketplace> [<key> [<value>]]` | the options a plugin asks for |
|
|
313
|
+
|
|
314
|
+
**What it runs is printed first.** Before a plugin is installed, every hook
|
|
315
|
+
command and MCP server it would run is printed, as it would run. It is
|
|
316
|
+
installed only with `--yes` or a `y` typed at the question; in a script or a
|
|
317
|
+
pipe with no `--yes`, the answer is no. An update that changes what it runs
|
|
318
|
+
asks again, and a no keeps the version you have.
|
|
319
|
+
|
|
320
|
+
A plugin's skills and commands are named `<plugin>:<name>` (`/hookify:list`),
|
|
321
|
+
and the bare name works while no other plugin has it. A sensitive option is
|
|
322
|
+
kept in the Keychain (or `secrets.json`, owner-only, in `~/.config/astracode`
|
|
323
|
+
elsewhere) and is never taken from the command line: run `plugin config`
|
|
324
|
+
without a value to type it, or pipe it in. Plugins are kept in
|
|
325
|
+
`~/.astracode/plugins`, each at the commit it was installed from.
|
|
326
|
+
|
|
327
|
+
A plugin's MCP servers start in the full-screen conversation, as your own
|
|
328
|
+
do. See [Plugins](https://astracode.io/docs/extending/plugins/).
|
|
269
329
|
|
|
270
330
|
## In Zed or a JetBrains IDE
|
|
271
331
|
|
|
@@ -311,12 +371,26 @@ or runs a command. **Always allow** applies to that tool for the rest of the
|
|
|
311
371
|
session. Risky commands and requests to other machines are asked about every
|
|
312
372
|
time.
|
|
313
373
|
|
|
374
|
+
**Running as one of your agents.** Each session has an **Agent** option
|
|
375
|
+
(an ACP session config option, id `agent`): AstraCode itself, or any agent
|
|
376
|
+
from `.astracode/agents`, `.claude/agents`, your home folder's or `--agents`.
|
|
377
|
+
Pick one and, from the next prompt, the session runs as that agent, as
|
|
378
|
+
`--agent` does on the command line: its prompt, its tools, its model tier and
|
|
379
|
+
the agents it may start. An editor that does not show config options can set a
|
|
380
|
+
starting agent for every session in its `args`:
|
|
381
|
+
|
|
382
|
+
```json
|
|
383
|
+
"args": ["acp", "--agents", "/Users/you/agents.json", "--agent", "reviewer"]
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
`--allow-agent-mcp` in the same `args` lets the project's agent files start
|
|
387
|
+
the MCP servers they declare; without it, only your own agent files' do.
|
|
314
388
|
|
|
315
389
|
|
|
316
390
|
These are not available without an editor:
|
|
317
391
|
|
|
318
392
|
- diagnostics and language-server lookups
|
|
319
|
-
- MCP servers
|
|
393
|
+
- the MCP servers in your settings (an agent file's own servers do start, as above)
|
|
320
394
|
- the code index
|
|
321
395
|
- memories and checkpoints
|
|
322
396
|
|
|
@@ -328,5 +402,7 @@ runners already have it.
|
|
|
328
402
|
| variable | |
|
|
329
403
|
|---|---|
|
|
330
404
|
| `ASTRACODE_API_KEY` | An `ac_live_` key. Takes precedence over a saved session. |
|
|
405
|
+
| `ASTRACODE_TRUST` | `1` trusts the folder for a conversation, `acp` or `review`, as `--trust` does. A `-p` run trusts it anyway. |
|
|
331
406
|
| `ASTRACODE_GATEWAY_URL` | The gateway to use. The default is `https://api.astracode.io`. |
|
|
332
407
|
| `ASTRACODE_CONFIG_DIR` | Keep the session in this folder instead of the Keychain or `~/.config/astracode`. |
|
|
408
|
+
| `ASTRACODE_PLUGINS_DIR` | Keep plugins and their state here instead of `~/.astracode/plugins`. |
|