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 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 a repository secret
267
- `ASTRACODE_TOKEN` (an API key with the "Run agents" scope) and Actions allowed
268
- to open pull requests. See [Remote agents](https://astracode.io/docs/agent/remote-agents/).
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`. |