@mumbrane/arrakis 0.8.3 → 0.12.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 +58 -1
- package/package.json +1 -1
- package/src/agent.js +51 -9
- package/src/anthropic.js +4 -1
- package/src/browser.js +427 -0
- package/src/checkpoints.js +9 -2
- package/src/cli.js +573 -46
- package/src/config.js +25 -0
- package/src/permissions.js +46 -4
- package/src/prompt.js +14 -1
- package/src/prompts.js +5 -2
- package/src/session.js +17 -1
- package/src/skills.js +122 -0
- package/src/theme.js +30 -0
- package/src/tools.js +142 -7
- package/src/tui.js +95 -12
- package/src/ui.js +16 -5
package/README.md
CHANGED
|
@@ -5,6 +5,9 @@ A coding agent for your terminal, built by Mumbrane. It reads your code, edits f
|
|
|
5
5
|
- **Sub-agents:** hands big jobs to parallel agents with their own fresh context
|
|
6
6
|
- **Plan mode:** investigates and proposes a plan before touching anything
|
|
7
7
|
- **Task lists:** tracks multi-step work as it goes
|
|
8
|
+
- **Skills:** packaged know-how the agent loads when a task calls for it
|
|
9
|
+
- **A real browser:** browses, clicks, types and takes screenshots it can look at
|
|
10
|
+
- **Deep research:** `/research` runs parallel web research and writes a cited report
|
|
8
11
|
- **Undo:** every file change is checkpointed; `/undo` puts things back
|
|
9
12
|
- **MCP:** plug in GitHub, databases, Slack and any other MCP server
|
|
10
13
|
- **Images:** attach screenshots and mockups
|
|
@@ -44,6 +47,8 @@ For CI or scripts, skip setup with environment variables: `ARRAKIS_PROVIDER` (e.
|
|
|
44
47
|
arrakis # interactive session in the current directory
|
|
45
48
|
arrakis "fix the failing test" # interactive, starting with a task
|
|
46
49
|
arrakis -p "explain src/app.ts" # one-shot: prints the answer and exits
|
|
50
|
+
arrakis -p --json "…" # one-shot with a JSON result (for scripts and CI)
|
|
51
|
+
arrakis -p --max-cost 0.50 "…" # stop if the estimated cost passes $0.50
|
|
47
52
|
arrakis -c # continue the last session in this directory
|
|
48
53
|
arrakis -r <id> # resume a specific session
|
|
49
54
|
arrakis sessions # list recent sessions
|
|
@@ -59,8 +64,15 @@ In a session:
|
|
|
59
64
|
| `/todos` | Show the current task list |
|
|
60
65
|
| `/cost` | Tokens, cache hits and estimated cost for this session |
|
|
61
66
|
| `/effort [level]` | How hard Claude thinks: `low` to `max` |
|
|
62
|
-
| `/resume` |
|
|
67
|
+
| `/resume` (or `/sessions`) | Pick an earlier session; its conversation is shown and you carry on in it |
|
|
68
|
+
| `/permissions` | See and revoke what is always allowed |
|
|
63
69
|
| `/export [file]` | Save the conversation as Markdown |
|
|
70
|
+
| `/memory` | Show or edit what arrakis remembers; start any message with `#` to add to it |
|
|
71
|
+
| `/diff` / `/commit` | Show uncommitted changes / have arrakis write the message and commit |
|
|
72
|
+
| `/rewind` (or Esc Esc) | Go back to before an earlier message: files are restored and your message comes back to edit |
|
|
73
|
+
| `/theme` | Color theme: auto, spice, spice-light, mono |
|
|
74
|
+
| `/budget [$]` | Stop when this session's estimated cost reaches a limit |
|
|
75
|
+
| `/rename [name]` | Name this session (shows in `/resume`) |
|
|
64
76
|
| `/undo [n]` | Revert arrakis's file changes from the last turn (or pick a turn) |
|
|
65
77
|
| `/paste` | Attach the image on your clipboard (macOS) |
|
|
66
78
|
| `/mcp` | Show connected MCP servers and their tools |
|
|
@@ -101,6 +113,51 @@ With the Anthropic provider, arrakis talks to the Claude API directly (through A
|
|
|
101
113
|
- **Fallbacks:** on models that support it, if Claude declines a request, the API can retry it on another Claude model.
|
|
102
114
|
- Sessions stay append-only: the system prompt is fixed for the session and Claude's responses are replayed exactly, which keeps the cache warm and Claude's earlier reasoning valid.
|
|
103
115
|
|
|
116
|
+
## Memory and permissions
|
|
117
|
+
|
|
118
|
+
Start a message with `#` to give arrakis a standing instruction, like `# use pnpm, not npm`. You choose whether it's for this project (`ARRAKIS.md`) or every project (`~/.arrakis/ARRAKIS.md`); `/memory` shows and edits both.
|
|
119
|
+
|
|
120
|
+
When arrakis wants to run a command, you can allow just that command for this project (for example `npm test`, which also covers `npm test -- --watch`). It's remembered in your own config, never in the repository, and a rule never covers chained or redirected commands (`;`, `&&`, `|`, `>`, `$( )`). `/permissions` lists and revokes them.
|
|
121
|
+
|
|
122
|
+
## Cost and speed
|
|
123
|
+
|
|
124
|
+
Set a faster, cheaper model for sub-agents, which do most of the reading in research and exploration:
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
arrakis config set subagentModel claude-haiku-5-5
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`arrakis doctor` checks Node, your provider and key, the model, the browser, MCP servers and skills.
|
|
131
|
+
|
|
132
|
+
Shortcuts: Esc Esc rewinds (or clears what you typed), Ctrl+R searches your earlier messages, Ctrl+O shows a tool's full output, Ctrl+V attaches the image on the clipboard (macOS), and a bell (plus a notification after a minute) tells you when a long task finishes.
|
|
133
|
+
|
|
134
|
+
## Skills
|
|
135
|
+
|
|
136
|
+
A skill is a folder with a `SKILL.md`: a name, a one-line description of when to use it, and the steps to follow. Scripts and templates can sit next to it. arrakis only puts the descriptions in context and loads a skill's instructions when a task matches, so you can keep many of them.
|
|
137
|
+
|
|
138
|
+
```markdown
|
|
139
|
+
---
|
|
140
|
+
name: release
|
|
141
|
+
description: Cut a release: bump the version, update the changelog, tag and publish.
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
1. Run the tests.
|
|
145
|
+
2. Bump the version in package.json …
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Skills live in `~/.arrakis/skills/<name>/` (everywhere) or `.arrakis/skills/<name>/` (one project). Skills in `~/.claude/skills` and `.claude/skills` work too. Run one directly as `/<name>`, or use `/skills` to browse, run or create them. A project's own skills need the folder to be trusted first.
|
|
149
|
+
|
|
150
|
+
## Browser, search and research
|
|
151
|
+
|
|
152
|
+
- **`web_search`** finds pages and **`web_fetch`** reads them. Search uses DuckDuckGo with no setup; set `TAVILY_API_KEY` or `BRAVE_SEARCH_API_KEY` to use those APIs instead.
|
|
153
|
+
- **`browser`** drives a real Chrome in its own profile (never your everyday one): open pages, read them, click, type, press keys, scroll, and take screenshots that the model looks at. It asks before clicking, typing or opening pages. It uses Chrome, Edge, Brave or Chromium if one is installed; otherwise run `arrakis browser install` to download Chrome for Testing (about 150 MB) into `~/.arrakis/browser`. Set `ARRAKIS_BROWSER_HEADFUL=1` to watch it in a window.
|
|
154
|
+
- **Images:** the model can open image files itself (`read_file` on a PNG returns the image), as well as images you attach.
|
|
155
|
+
- **`/research <question>`** plans sub-questions, researches them in parallel with sub-agents, follows up on gaps, and writes a report with numbered citations to `research/<topic>.md`.
|
|
156
|
+
|
|
157
|
+
## Long sessions
|
|
158
|
+
|
|
159
|
+
Sessions can run for hours. When the history nears the context window, older turns are summarized automatically (at 80%; you get a heads-up at 65%), and `/compact <what to keep>` lets you steer the summary. The task list is saved with the session and comes back on resume, and every session can be reopened with `/resume`.
|
|
160
|
+
|
|
104
161
|
## Undo
|
|
105
162
|
|
|
106
163
|
Before arrakis writes or edits a file, it saves the original. `/undo` reverts the last turn's changes; with several turns it lets you pick how far back to go. Checkpoints are stored with the session, so undo still works after `arrakis -c`. Changes made by shell commands (`bash`) aren't tracked, so use git for those.
|
package/package.json
CHANGED
package/src/agent.js
CHANGED
|
@@ -5,8 +5,8 @@ import { Session } from './session.js';
|
|
|
5
5
|
import { isNativeAnthropic, streamAnthropic, completeAnthropic } from './anthropic.js';
|
|
6
6
|
import { Usage } from './pricing.js';
|
|
7
7
|
|
|
8
|
-
const MAX_STEPS =
|
|
9
|
-
const MAX_SUB_STEPS =
|
|
8
|
+
const MAX_STEPS = 1500;
|
|
9
|
+
const MAX_SUB_STEPS = 300;
|
|
10
10
|
const COMPACT_AT = 0.8;
|
|
11
11
|
const KEEP_RECENT = 6;
|
|
12
12
|
|
|
@@ -17,6 +17,7 @@ export function estimateTokens(messages) {
|
|
|
17
17
|
if (Array.isArray(m.content)) for (const p of m.content) chars += p.type === 'image_url' ? 6400 : String(p.text ?? '').length;
|
|
18
18
|
else chars += String(m.content ?? '').length;
|
|
19
19
|
if (m.tool_calls) chars += JSON.stringify(m.tool_calls).length;
|
|
20
|
+
if (m.images) chars += m.images.length * 6400;
|
|
20
21
|
chars += 16;
|
|
21
22
|
}
|
|
22
23
|
return Math.ceil(chars / 4);
|
|
@@ -57,7 +58,8 @@ export class Agent {
|
|
|
57
58
|
}
|
|
58
59
|
|
|
59
60
|
allowsTool(name) {
|
|
60
|
-
|
|
61
|
+
// Sub-agents don't spawn sub-agents, keep the task list, or share the one browser.
|
|
62
|
+
if (this.depth > 0 && (name === 'task' || name === 'todo_write' || name === 'browser')) return false;
|
|
61
63
|
return this.toolFilter ? this.toolFilter(name) : true;
|
|
62
64
|
}
|
|
63
65
|
|
|
@@ -84,7 +86,7 @@ export class Agent {
|
|
|
84
86
|
content = typeof input === 'string' ? `${input}\n\n${note}` : [...input, { type: 'text', text: note }];
|
|
85
87
|
}
|
|
86
88
|
this.session.add({ role: 'user', content });
|
|
87
|
-
if (this.depth === 0) this.checkpoints?.beginTurn(typeof input === 'string' ? input : input.find((p) => p.type === 'text')?.text ?? '(message)');
|
|
89
|
+
if (this.depth === 0) this.checkpoints?.beginTurn(typeof input === 'string' ? input : input.find((p) => p.type === 'text')?.text ?? '(message)', this.session.messages.length - 1);
|
|
88
90
|
this.abort = new AbortController();
|
|
89
91
|
const signal = this.abort.signal;
|
|
90
92
|
const onParentAbort = () => this.abort?.abort();
|
|
@@ -95,8 +97,14 @@ export class Agent {
|
|
|
95
97
|
for (let step = 0; step < limit; step++) {
|
|
96
98
|
await this.maybeCompact(signal);
|
|
97
99
|
const msg = await this.callModel(signal);
|
|
100
|
+
if (this.depth === 0 && this.budget && this.usage.cost >= this.budget) {
|
|
101
|
+
this.lastError = 'Budget reached.';
|
|
102
|
+
this.ui.error(`Budget reached: about $${this.usage.cost.toFixed(2)} of your $${this.budget.toFixed(2)} limit. Raise it with /budget <dollars>, or /budget off.`);
|
|
103
|
+
return false;
|
|
104
|
+
}
|
|
98
105
|
if (!msg.tool_calls?.length) {
|
|
99
106
|
if (this.depth === 0 && this.hooks) await this.hooks.run('Stop', { sessionId: this.session.id });
|
|
107
|
+
if (this.depth === 0) this.warnContext();
|
|
100
108
|
return true;
|
|
101
109
|
}
|
|
102
110
|
await this.runTools(msg.tool_calls, signal);
|
|
@@ -152,14 +160,18 @@ export class Agent {
|
|
|
152
160
|
}
|
|
153
161
|
}
|
|
154
162
|
if (!this.silent) this.ui.stopSpinner();
|
|
155
|
-
calls.forEach((call, i) =>
|
|
163
|
+
calls.forEach((call, i) => {
|
|
164
|
+
const r = results[i];
|
|
165
|
+
if (r && typeof r === 'object') this.session.add({ role: 'tool', tool_call_id: call.id, content: r.text, images: r.images });
|
|
166
|
+
else this.session.add({ role: 'tool', tool_call_id: call.id, content: r });
|
|
167
|
+
});
|
|
156
168
|
}
|
|
157
169
|
|
|
158
170
|
async runSubagent({ description = 'sub-task', prompt, agent_type = 'explore' }, signal) {
|
|
159
171
|
if (!prompt) throw new Error('prompt is required');
|
|
160
172
|
const readOnly = agent_type !== 'general';
|
|
161
173
|
const sub = new Agent({
|
|
162
|
-
config: this.config,
|
|
174
|
+
config: this.config.subagentModel ? { ...this.config, model: this.config.subagentModel } : this.config,
|
|
163
175
|
session: Session.memory(),
|
|
164
176
|
ui: this.ui,
|
|
165
177
|
permissions: this.permissions,
|
|
@@ -250,7 +262,27 @@ export class Agent {
|
|
|
250
262
|
return msg;
|
|
251
263
|
}
|
|
252
264
|
|
|
253
|
-
async callOpenAI(
|
|
265
|
+
async callOpenAI(history, tools, signal) {
|
|
266
|
+
// OpenAI-style APIs only take text in tool messages, so images from a run
|
|
267
|
+
// of tool results go in one user message right after that run.
|
|
268
|
+
const messages = [];
|
|
269
|
+
let pending = [];
|
|
270
|
+
const flush = () => {
|
|
271
|
+
if (!pending.length) return;
|
|
272
|
+
messages.push({ role: 'user', content: [{ type: 'text', text: '(Images returned by the tool calls above.)' }, ...pending.map((url) => ({ type: 'image_url', image_url: { url } }))] });
|
|
273
|
+
pending = [];
|
|
274
|
+
};
|
|
275
|
+
for (const m of history) {
|
|
276
|
+
if (m.role === 'tool') {
|
|
277
|
+
const { images, ...rest } = m;
|
|
278
|
+
messages.push(rest);
|
|
279
|
+
if (images?.length) pending.push(...images);
|
|
280
|
+
continue;
|
|
281
|
+
}
|
|
282
|
+
flush();
|
|
283
|
+
messages.push(m);
|
|
284
|
+
}
|
|
285
|
+
flush();
|
|
254
286
|
let content = '';
|
|
255
287
|
const calls = [];
|
|
256
288
|
for await (const event of streamChat({ config: this.config, messages, tools, signal })) {
|
|
@@ -285,7 +317,16 @@ export class Agent {
|
|
|
285
317
|
return isNativeAnthropic(this.config) ? completeAnthropic({ config: this.config, messages, signal }) : completeText({ config: this.config, messages, signal });
|
|
286
318
|
}
|
|
287
319
|
|
|
288
|
-
|
|
320
|
+
// Once per session, say when the context is getting full.
|
|
321
|
+
warnContext() {
|
|
322
|
+
const used = estimateTokens(this.session.messages) / this.config.contextWindow;
|
|
323
|
+
if (used >= 0.65 && !this.warnedContext) {
|
|
324
|
+
this.warnedContext = true;
|
|
325
|
+
this.ui.info(` Context is ${Math.round(used * 100)}% full. At 80% arrakis summarizes older turns automatically; run /compact <what to keep> to do it now and choose what matters.`);
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
async maybeCompact(signal, force = false, focus = '') {
|
|
289
330
|
const messages = this.session.messages;
|
|
290
331
|
if (!force && estimateTokens(messages) < this.config.contextWindow * COMPACT_AT) return false;
|
|
291
332
|
// Cut at a user message so tool calls stay paired with their results.
|
|
@@ -308,12 +349,13 @@ export class Agent {
|
|
|
308
349
|
{ role: 'system', content: 'You summarize coding-agent conversations so the work can continue with less context.' },
|
|
309
350
|
{
|
|
310
351
|
role: 'user',
|
|
311
|
-
content: `Summarize this conversation between a user and a coding agent. Keep: the user's goals and instructions, decisions made, files read or changed (with paths), commands run and their important results, errors hit, the current task list, and what is left to do. Be specific and concise
|
|
352
|
+
content: `Summarize this conversation between a user and a coding agent. Keep: the user's goals and instructions, decisions made, files read or changed (with paths), commands run and their important results, errors hit, the current task list, and what is left to do. Be specific and concise.${focus ? `\n\nThe user asked you to make sure the summary keeps: ${focus}` : ''}${this.todos.length ? `\n\nCurrent task list:\n${this.todos.map((t) => `- [${t.status}] ${t.content}`).join('\n')}` : ''}\n\n<conversation>\n${truncate(transcript, 400000)}\n</conversation>`,
|
|
312
353
|
},
|
|
313
354
|
],
|
|
314
355
|
signal,
|
|
315
356
|
);
|
|
316
357
|
this.session.compact(summary.trim() || '(no summary produced)', cut);
|
|
358
|
+
this.warnedContext = false;
|
|
317
359
|
if (estimateTokens(this.session.messages) >= this.config.contextWindow * COMPACT_AT) this.trimToolResults();
|
|
318
360
|
return true;
|
|
319
361
|
}
|
package/src/anthropic.js
CHANGED
|
@@ -70,7 +70,10 @@ export function toAnthropic(history) {
|
|
|
70
70
|
} else if (m.role === 'user') push('user', userBlocks(m.content));
|
|
71
71
|
else if (m.role === 'tool') {
|
|
72
72
|
const text = String(m.content ?? '');
|
|
73
|
-
|
|
73
|
+
const err = /^(Error|Permission denied|Blocked)/.test(text) ? { is_error: true } : {};
|
|
74
|
+
const images = (m.images ?? []).map((url) => url.match(dataUrl)).filter(Boolean).map((x) => ({ type: 'image', source: { type: 'base64', media_type: x[1], data: x[2] } }));
|
|
75
|
+
const content = images.length ? [{ type: 'text', text: text || '(image)' }, ...images] : text || '(no output)';
|
|
76
|
+
push('user', [{ type: 'tool_result', tool_use_id: m.tool_call_id, content, ...err }]);
|
|
74
77
|
} else if (m.role === 'assistant') {
|
|
75
78
|
if (Array.isArray(m.anthropic) && m.anthropic.length) {
|
|
76
79
|
push('assistant', m.anthropic);
|