@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 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` | Switch to an earlier session |
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mumbrane/arrakis",
3
- "version": "0.8.3",
3
+ "version": "0.12.0",
4
4
  "description": "Arrakis: a coding agent for your terminal, built by Mumbrane",
5
5
  "type": "module",
6
6
  "main": "./index.js",
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 = 400;
9
- const MAX_SUB_STEPS = 150;
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
- if (this.depth > 0 && (name === 'task' || name === 'todo_write')) return false;
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) => this.session.add({ role: 'tool', tool_call_id: call.id, content: results[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(messages, tools, signal) {
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
- async maybeCompact(signal, force = false) {
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.\n\n<conversation>\n${truncate(transcript, 400000)}\n</conversation>`,
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
- push('user', [{ type: 'tool_result', tool_use_id: m.tool_call_id, content: text || '(no output)', ...(/^(Error|Permission denied|Blocked)/.test(text) ? { is_error: true } : {}) }]);
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);