@falkenslab/agent-kit 0.31.0 → 0.33.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 +175 -175
- package/dist/chat/chatController.d.ts +5 -0
- package/dist/chat/chatController.js +13 -0
- package/dist/core/claudeAuth.d.ts +53 -21
- package/dist/core/claudeAuth.js +135 -22
- package/dist/core/hooks/transcriptLogger.d.ts +2 -2
- package/dist/core/hooks/transcriptLogger.js +2 -2
- package/dist/core/mcpDepth.d.ts +9 -0
- package/dist/core/mcpDepth.js +12 -0
- package/dist/core/messages/de.js +9 -7
- package/dist/core/messages/en.d.ts +7 -5
- package/dist/core/messages/en.js +9 -7
- package/dist/core/messages/es.js +9 -7
- package/dist/core/messages/fr.js +9 -7
- package/dist/core/packaged.d.ts +6 -0
- package/dist/core/packaged.js +18 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/mcp/index.d.ts +1 -0
- package/dist/mcp/index.js +1 -0
- package/dist/mcp/serveMcp.d.ts +28 -0
- package/dist/mcp/serveMcp.js +177 -0
- package/dist/tui/claudeAuth.d.ts +12 -17
- package/dist/tui/claudeAuth.js +37 -66
- package/package.json +13 -1
package/README.md
CHANGED
|
@@ -1,175 +1,175 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/static/img/logo.svg" alt="agent-kit logo: three blue building blocks and a coral one being set in place" width="112"/>
|
|
4
|
-
|
|
5
|
-
# agent-kit
|
|
6
|
-
|
|
7
|
-
**Build an AI agent on Claude that asks before it acts, remembers, and chats like Claude Code.**<br/>
|
|
8
|
-
You write what your agent knows and does; the kit brings oversight, safety, memory and the interface.
|
|
9
|
-
|
|
10
|
-
[](https://www.npmjs.com/package/@falkenslab/agent-kit)
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
[](LICENSE)
|
|
15
|
-
|
|
16
|
-
**[📖 Documentation](https://falkenslab.github.io/agent-kit/)** · [📖 Documentación en español](https://falkenslab.github.io/agent-kit/es/)
|
|
17
|
-
|
|
18
|
-
</div>
|
|
19
|
-
|
|
20
|
-
agent-kit is a foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (levels of oversight, approvals, safe limits, memory across sessions, extensions, and a terminal chat as good as Claude Code's), so each agent writes only what belongs to its own domain: what it knows how to do, with which tools, and how it talks. A teacher's assistant for Moodle and a pirate cat who tells jokes are built the same way.
|
|
21
|
-
|
|
22
|
-
## ✨ Why agent-kit
|
|
23
|
-
|
|
24
|
-
- 🎚️ **You choose how much it acts alone.** Autonomous, guided (it asks before what others will see or can't be undone), step by step, or a plan mode where it only reads and plans; switch among them in the same conversation.
|
|
25
|
-
- ✋ **It asks a person, and the kit makes sure.** Approvals, choices, a file, a sign-in by hand; an installed extension's tool that changes things waits for a yes whatever the model decided, and answers can last for the session or for good.
|
|
26
|
-
- 🧠 **It remembers.** A knowledge base that grows with every session, the original documents it learns from kept untouched, a memory of the person, and every conversation to pick up again with `--continue` or `/resume`.
|
|
27
|
-
- 🛡️ **It stays within limits.** Only its own folders, never protected files, subagents that can't slip past the main agent's limits, secrets hidden from the logs, remote servers allowed, asked about or denied.
|
|
28
|
-
- 🧩 **It grows with extensions.** Claude Code plugins with MCP servers, skills and commands, installed from a marketplace or a folder, with their own options, sign-in and a catalog in the chat; no Git needed.
|
|
29
|
-
- 🌐 **It speaks your language.** Its interface in English, Spanish, French or German, and it answers in that language unless you write in another.
|
|
30
|
-
- 🖥️ **A terminal chat like Claude Code's, or none at all.** Full screen, live markdown, folded tool calls, panels, history, themes; or the same agent inside a desktop app or a web page with its own interface.
|
|
31
|
-
|
|
32
|
-
## 🚀 Quick start
|
|
33
|
-
|
|
34
|
-
You need [Node.js](https://nodejs.org) 20 or later and a Claude account. In a project with `"type": "module"` in its `package.json`:
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
npm install @falkenslab/agent-kit tsx
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
Save this as `agent.ts`: the only part that's your agent's is the spec at the top.
|
|
41
|
-
|
|
42
|
-
```ts
|
|
43
|
-
import path from "node:path";
|
|
44
|
-
import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
|
|
45
|
-
|
|
46
|
-
const spec: AgentSpec<BaseSessionConfig> = {
|
|
47
|
-
buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
|
|
48
|
-
buildMcpServers: () => ({}), // its own MCP servers, if any
|
|
49
|
-
pluginRoots: () => [], // folders with skills and commands
|
|
50
|
-
buildSubagents: () => undefined, // subagents, if it delegates to any
|
|
51
|
-
};
|
|
52
|
-
|
|
53
|
-
await ensureClaudeAuth(); // offers to
|
|
54
|
-
const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
|
|
55
|
-
|
|
56
|
-
// Each run gets a folder under .run/ (keep it out of git): its log, transcript and conversation.
|
|
57
|
-
await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
|
|
58
|
-
runsDir: path.resolve(".run"),
|
|
59
|
-
header: { title: "My agent" },
|
|
60
|
-
mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
|
|
61
|
-
fullscreen: true,
|
|
62
|
-
});
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
Run it with `npx tsx agent.ts`: a full-screen chat opens, in your system's language, and the agent asks before anything it shouldn't do alone. The [tutorial](https://falkenslab.github.io/agent-kit/docs/getting-started/first-agent) takes it from there.
|
|
66
|
-
|
|
67
|
-
## 🧪 A taste of the code
|
|
68
|
-
|
|
69
|
-
Give it a memory and a folder of sources, with the kit's own extensions:
|
|
70
|
-
|
|
71
|
-
```ts
|
|
72
|
-
import { knowledge, memory, sources } from "@falkenslab/agent-kit";
|
|
73
|
-
|
|
74
|
-
const spec: AgentSpec<BaseSessionConfig> = {
|
|
75
|
-
// …
|
|
76
|
-
extensions: [sources({ dir: "sources" }), knowledge({ dir: "knowledge" }), memory({ dir: "memory" })],
|
|
77
|
-
};
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
Let it install extensions from your marketplace, and keep its data from leaving the computer without asking:
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
const config: BaseSessionConfig = {
|
|
84
|
-
mode: "guided",
|
|
85
|
-
projectDir: process.cwd(),
|
|
86
|
-
extensionDirs: { agent: path.join(os.homedir(), ".my-agent", "extensions") },
|
|
87
|
-
officialMarketplace: "falkenslab/agent-extensions",
|
|
88
|
-
remoteServers: "ask",
|
|
89
|
-
};
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Make a tool always wait for the person's yes, on every call:
|
|
93
|
-
|
|
94
|
-
```ts
|
|
95
|
-
const spec: AgentSpec<BaseSessionConfig> = {
|
|
96
|
-
// …
|
|
97
|
-
extensionGate: { confirmTools: { canva: ["create-design", "publish-design"] } },
|
|
98
|
-
};
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
## 📸 See it at work
|
|
102
|
-
|
|
103
|
-
[Captain Whiskers](./examples/captain-whiskers), the kit's example agent: a retired pirate cat who tells jokes in your language, with a crew of subagents (one looks for new jokes on the web, one rates them, one tells the time), a logbook and an extension of his own. He runs in the terminal, in a browser and as a Windows app.
|
|
104
|
-
|
|
105
|
-
<div align="center">
|
|
106
|
-
|
|
107
|
-
<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/assets/captain-whiskers.png" alt="Captain Whiskers in Windows Terminal: his logo with the mode and the agent-kit version at the top, his crew at work in the middle, a task list under the spinner, and the framed prompt and status bar at the bottom" width="760"/>
|
|
108
|
-
|
|
109
|
-
</div>
|
|
110
|
-
|
|
111
|
-
See [everything he can do](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers#what-he-can-do), with screenshots. For a real one, [miyagi](https://github.com/falkenslab/miyagi) is an assistant for Moodle teachers: it grades, answers the forum, builds content and sums up how the class is going, asking before publishing anything students will see. Oversight, memory, safety and the chat come from the kit; miyagi brings what it knows about Moodle.
|
|
112
|
-
|
|
113
|
-
## 🧰 What's inside
|
|
114
|
-
|
|
115
|
-
| Area | For example |
|
|
116
|
-
| --- | --- |
|
|
117
|
-
| 🎚️ Modes and gates | Autonomous, guided, step by step and plan; the guided gate for extensions' tools, the plan gate, the step gate |
|
|
118
|
-
| ✋ Human in the loop | Approvals, choices, free text, files, manual steps, MCP elicitation forms, a response file for hosts without a keyboard |
|
|
119
|
-
| 🧠 Memory | A knowledge base (an LLM wiki), sources kept as obtained, a memory of the person, runs resumed with `--continue` and `/resume` |
|
|
120
|
-
| 🧩 Extensions | Claude Code plugins with MCP servers (local, npm, remote with OAuth), skills, commands and subagents; scopes, a lock, workspace trust, options, marketplaces and a catalog |
|
|
121
|
-
| 🛡️ Security | A file scope gate, denied paths, subagent gates, a remote-servers gate, isolation from the runner's own Claude Code, redacted transcripts |
|
|
122
|
-
| 🤖 Subagents | Declared types only, in the foreground, without Bash for the main agent |
|
|
123
|
-
| 🖥️ Interfaces | A full-screen Ink chat, a plain readline chat, a progress view, a wizard, themes; a chat controller for desktop apps and web pages |
|
|
124
|
-
| 🌐 Languages | English, Spanish, French and German, for the interface, the replies and the extensions' servers |
|
|
125
|
-
|
|
126
|
-
Every export, with what it takes and what it gives, is in the [API reference](https://falkenslab.github.io/agent-kit/docs/api).
|
|
127
|
-
|
|
128
|
-
## 📚 Documentation
|
|
129
|
-
|
|
130
|
-
- **[Getting started](https://falkenslab.github.io/agent-kit/docs/getting-started/installation)**: installation and a first agent, step by step.
|
|
131
|
-
- **[Modes](https://falkenslab.github.io/agent-kit/docs/core-concepts/modes)** and **[human in the loop](https://falkenslab.github.io/agent-kit/docs/human-in-the-loop/overview)**: how much the agent does alone, and how it asks.
|
|
132
|
-
- **[Extensions](https://falkenslab.github.io/agent-kit/docs/extensions/overview)**: installing, writing and publishing them.
|
|
133
|
-
- **[Security](https://falkenslab.github.io/agent-kit/docs/security/overview)**: every guardrail, and what the kit doesn't protect.
|
|
134
|
-
- **[The terminal chat](https://falkenslab.github.io/agent-kit/docs/terminal-ui/ink-chat)**: its keys, panels, options and themes.
|
|
135
|
-
- **[Captain Whiskers](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers)**: the example agent, piece by piece.
|
|
136
|
-
|
|
137
|
-
## 🛠️ Developing
|
|
138
|
-
|
|
139
|
-
The design decisions, and the SDK behaviors checked by hand behind several safeguards, are in [`.minispec/`](./.minispec/README.md).
|
|
140
|
-
|
|
141
|
-
| Command | What it does |
|
|
142
|
-
| --- | --- |
|
|
143
|
-
| `npm run build` | Builds the kit into `dist/` |
|
|
144
|
-
| `npm run typecheck` | Checks the types without building |
|
|
145
|
-
| `npm run lint` | Checks the code style |
|
|
146
|
-
| `npm test` | Runs all the tests (one file: `npx tsx --test test/tui/promptErrors.test.ts`) |
|
|
147
|
-
| `npm run docs:install` | Installs the documentation site's dependencies (once) |
|
|
148
|
-
| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
|
|
149
|
-
| `npm run docs:build` | Builds the documentation site (fails on broken links) |
|
|
150
|
-
|
|
151
|
-
To try changes to the kit in an agent without publishing them, point its `package.json` to a local clone (`"file:../agent-kit"`) and run `npm run build` after each change.
|
|
152
|
-
|
|
153
|
-
Working on the kit with Claude Code goes through Falken's Lab's own skills (commit, verify, update-docs, release, sync-issues, and the house style for READMEs, sites and Markdown), from the [falkenslab/falkenslab-plugins](https://github.com/falkenslab/falkenslab-plugins) marketplace. Install them once, for all of Falken's Lab's repositories:
|
|
154
|
-
|
|
155
|
-
```bash
|
|
156
|
-
claude plugin marketplace add falkenslab/falkenslab-plugins
|
|
157
|
-
claude plugin install falkenslab-dev@falkenslab-plugins
|
|
158
|
-
claude plugin install falkenslab-style@falkenslab-plugins
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
<details>
|
|
162
|
-
<summary>What each plugin brings, and what stays in this repository</summary>
|
|
163
|
-
|
|
164
|
-
- 🔧 **falkenslab-dev**: `commit`, `verify`, `update-docs`, `release`, `sync-issues`, `upgrade-deps` and `add-tool`.
|
|
165
|
-
- 🎨 **falkenslab-style**: `falkenslab-docs`, `falkenslab-site-style`, `falkenslab-terminal-screenshots` and `markdown-writing`.
|
|
166
|
-
|
|
167
|
-
Inside Claude Code, the same with `/plugin marketplace add falkenslab/falkenslab-plugins` and `/plugin install falkenslab-dev@falkenslab-plugins`; `/plugin marketplace update falkenslab-plugins` brings their latest version. This repository keeps only the skills that are agent-kit's own, in `.claude/skills/` (`add-export`, the MiniSpec ones and `upgrade-sdk`), and what its release adds to the general one is in [`CLAUDE.md`](./CLAUDE.md#releasing).
|
|
168
|
-
|
|
169
|
-
</details>
|
|
170
|
-
|
|
171
|
-
<div align="center">
|
|
172
|
-
|
|
173
|
-
Made with 💖 by Falken's Lab Team
|
|
174
|
-
|
|
175
|
-
</div>
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/static/img/logo.svg" alt="agent-kit logo: three blue building blocks and a coral one being set in place" width="112"/>
|
|
4
|
+
|
|
5
|
+
# agent-kit
|
|
6
|
+
|
|
7
|
+
**Build an AI agent on Claude that asks before it acts, remembers, and chats like Claude Code.**<br/>
|
|
8
|
+
You write what your agent knows and does; the kit brings oversight, safety, memory and the interface.
|
|
9
|
+
|
|
10
|
+
[](https://www.npmjs.com/package/@falkenslab/agent-kit)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
[](LICENSE)
|
|
15
|
+
|
|
16
|
+
**[📖 Documentation](https://falkenslab.github.io/agent-kit/)** · [📖 Documentación en español](https://falkenslab.github.io/agent-kit/es/)
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
agent-kit is a foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (levels of oversight, approvals, safe limits, memory across sessions, extensions, and a terminal chat as good as Claude Code's), so each agent writes only what belongs to its own domain: what it knows how to do, with which tools, and how it talks. A teacher's assistant for Moodle and a pirate cat who tells jokes are built the same way.
|
|
21
|
+
|
|
22
|
+
## ✨ Why agent-kit
|
|
23
|
+
|
|
24
|
+
- 🎚️ **You choose how much it acts alone.** Autonomous, guided (it asks before what others will see or can't be undone), step by step, or a plan mode where it only reads and plans; switch among them in the same conversation.
|
|
25
|
+
- ✋ **It asks a person, and the kit makes sure.** Approvals, choices, a file, a sign-in by hand; an installed extension's tool that changes things waits for a yes whatever the model decided, and answers can last for the session or for good.
|
|
26
|
+
- 🧠 **It remembers.** A knowledge base that grows with every session, the original documents it learns from kept untouched, a memory of the person, and every conversation to pick up again with `--continue` or `/resume`.
|
|
27
|
+
- 🛡️ **It stays within limits.** Only its own folders, never protected files, subagents that can't slip past the main agent's limits, secrets hidden from the logs, remote servers allowed, asked about or denied.
|
|
28
|
+
- 🧩 **It grows with extensions.** Claude Code plugins with MCP servers, skills and commands, installed from a marketplace or a folder, with their own options, sign-in and a catalog in the chat; no Git needed.
|
|
29
|
+
- 🌐 **It speaks your language.** Its interface in English, Spanish, French or German, and it answers in that language unless you write in another.
|
|
30
|
+
- 🖥️ **A terminal chat like Claude Code's, or none at all.** Full screen, live markdown, folded tool calls, panels, history, themes; or the same agent inside a desktop app or a web page with its own interface.
|
|
31
|
+
|
|
32
|
+
## 🚀 Quick start
|
|
33
|
+
|
|
34
|
+
You need [Node.js](https://nodejs.org) 20 or later and a Claude account. In a project with `"type": "module"` in its `package.json`:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npm install @falkenslab/agent-kit tsx
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Save this as `agent.ts`: the only part that's your agent's is the spec at the top.
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import path from "node:path";
|
|
44
|
+
import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
|
|
45
|
+
|
|
46
|
+
const spec: AgentSpec<BaseSessionConfig> = {
|
|
47
|
+
buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
|
|
48
|
+
buildMcpServers: () => ({}), // its own MCP servers, if any
|
|
49
|
+
pluginRoots: () => [], // folders with skills and commands
|
|
50
|
+
buildSubagents: () => undefined, // subagents, if it delegates to any
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
await ensureClaudeAuth(); // offers to sign in with your Claude account, on Anthropic's page, if it isn't
|
|
54
|
+
const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
|
|
55
|
+
|
|
56
|
+
// Each run gets a folder under .run/ (keep it out of git): its log, transcript and conversation.
|
|
57
|
+
await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
|
|
58
|
+
runsDir: path.resolve(".run"),
|
|
59
|
+
header: { title: "My agent" },
|
|
60
|
+
mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
|
|
61
|
+
fullscreen: true,
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Run it with `npx tsx agent.ts`: a full-screen chat opens, in your system's language, and the agent asks before anything it shouldn't do alone. The [tutorial](https://falkenslab.github.io/agent-kit/docs/getting-started/first-agent) takes it from there.
|
|
66
|
+
|
|
67
|
+
## 🧪 A taste of the code
|
|
68
|
+
|
|
69
|
+
Give it a memory and a folder of sources, with the kit's own extensions:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { knowledge, memory, sources } from "@falkenslab/agent-kit";
|
|
73
|
+
|
|
74
|
+
const spec: AgentSpec<BaseSessionConfig> = {
|
|
75
|
+
// …
|
|
76
|
+
extensions: [sources({ dir: "sources" }), knowledge({ dir: "knowledge" }), memory({ dir: "memory" })],
|
|
77
|
+
};
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Let it install extensions from your marketplace, and keep its data from leaving the computer without asking:
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
const config: BaseSessionConfig = {
|
|
84
|
+
mode: "guided",
|
|
85
|
+
projectDir: process.cwd(),
|
|
86
|
+
extensionDirs: { agent: path.join(os.homedir(), ".my-agent", "extensions") },
|
|
87
|
+
officialMarketplace: "falkenslab/agent-extensions",
|
|
88
|
+
remoteServers: "ask",
|
|
89
|
+
};
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Make a tool always wait for the person's yes, on every call:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
const spec: AgentSpec<BaseSessionConfig> = {
|
|
96
|
+
// …
|
|
97
|
+
extensionGate: { confirmTools: { canva: ["create-design", "publish-design"] } },
|
|
98
|
+
};
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## 📸 See it at work
|
|
102
|
+
|
|
103
|
+
[Captain Whiskers](./examples/captain-whiskers), the kit's example agent: a retired pirate cat who tells jokes in your language, with a crew of subagents (one looks for new jokes on the web, one rates them, one tells the time), a logbook and an extension of his own. He runs in the terminal, in a browser and as a Windows app.
|
|
104
|
+
|
|
105
|
+
<div align="center">
|
|
106
|
+
|
|
107
|
+
<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/assets/captain-whiskers.png" alt="Captain Whiskers in Windows Terminal: his logo with the mode and the agent-kit version at the top, his crew at work in the middle, a task list under the spinner, and the framed prompt and status bar at the bottom" width="760"/>
|
|
108
|
+
|
|
109
|
+
</div>
|
|
110
|
+
|
|
111
|
+
See [everything he can do](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers#what-he-can-do), with screenshots. For a real one, [miyagi](https://github.com/falkenslab/miyagi) is an assistant for Moodle teachers: it grades, answers the forum, builds content and sums up how the class is going, asking before publishing anything students will see. Oversight, memory, safety and the chat come from the kit; miyagi brings what it knows about Moodle.
|
|
112
|
+
|
|
113
|
+
## 🧰 What's inside
|
|
114
|
+
|
|
115
|
+
| Area | For example |
|
|
116
|
+
| --- | --- |
|
|
117
|
+
| 🎚️ Modes and gates | Autonomous, guided, step by step and plan; the guided gate for extensions' tools, the plan gate, the step gate |
|
|
118
|
+
| ✋ Human in the loop | Approvals, choices, free text, files, manual steps, MCP elicitation forms, a response file for hosts without a keyboard |
|
|
119
|
+
| 🧠 Memory | A knowledge base (an LLM wiki), sources kept as obtained, a memory of the person, runs resumed with `--continue` and `/resume` |
|
|
120
|
+
| 🧩 Extensions | Claude Code plugins with MCP servers (local, npm, remote with OAuth), skills, commands and subagents; scopes, a lock, workspace trust, options, marketplaces and a catalog |
|
|
121
|
+
| 🛡️ Security | A file scope gate, denied paths, subagent gates, a remote-servers gate, isolation from the runner's own Claude Code, redacted transcripts |
|
|
122
|
+
| 🤖 Subagents | Declared types only, in the foreground, without Bash for the main agent |
|
|
123
|
+
| 🖥️ Interfaces | A full-screen Ink chat, a plain readline chat, a progress view, a wizard, themes; a chat controller for desktop apps and web pages; an MCP server, so other agents can ask it things |
|
|
124
|
+
| 🌐 Languages | English, Spanish, French and German, for the interface, the replies and the extensions' servers |
|
|
125
|
+
|
|
126
|
+
Every export, with what it takes and what it gives, is in the [API reference](https://falkenslab.github.io/agent-kit/docs/api).
|
|
127
|
+
|
|
128
|
+
## 📚 Documentation
|
|
129
|
+
|
|
130
|
+
- **[Getting started](https://falkenslab.github.io/agent-kit/docs/getting-started/installation)**: installation and a first agent, step by step.
|
|
131
|
+
- **[Modes](https://falkenslab.github.io/agent-kit/docs/core-concepts/modes)** and **[human in the loop](https://falkenslab.github.io/agent-kit/docs/human-in-the-loop/overview)**: how much the agent does alone, and how it asks.
|
|
132
|
+
- **[Extensions](https://falkenslab.github.io/agent-kit/docs/extensions/overview)**: installing, writing and publishing them.
|
|
133
|
+
- **[Security](https://falkenslab.github.io/agent-kit/docs/security/overview)**: every guardrail, and what the kit doesn't protect.
|
|
134
|
+
- **[The terminal chat](https://falkenslab.github.io/agent-kit/docs/terminal-ui/ink-chat)**: its keys, panels, options and themes.
|
|
135
|
+
- **[Captain Whiskers](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers)**: the example agent, piece by piece.
|
|
136
|
+
|
|
137
|
+
## 🛠️ Developing
|
|
138
|
+
|
|
139
|
+
The design decisions, and the SDK behaviors checked by hand behind several safeguards, are in [`.minispec/`](./.minispec/README.md).
|
|
140
|
+
|
|
141
|
+
| Command | What it does |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| `npm run build` | Builds the kit into `dist/` |
|
|
144
|
+
| `npm run typecheck` | Checks the types without building |
|
|
145
|
+
| `npm run lint` | Checks the code style |
|
|
146
|
+
| `npm test` | Runs all the tests (one file: `npx tsx --test test/tui/promptErrors.test.ts`) |
|
|
147
|
+
| `npm run docs:install` | Installs the documentation site's dependencies (once) |
|
|
148
|
+
| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
|
|
149
|
+
| `npm run docs:build` | Builds the documentation site (fails on broken links) |
|
|
150
|
+
|
|
151
|
+
To try changes to the kit in an agent without publishing them, point its `package.json` to a local clone (`"file:../agent-kit"`) and run `npm run build` after each change.
|
|
152
|
+
|
|
153
|
+
Working on the kit with Claude Code goes through Falken's Lab's own skills (commit, verify, update-docs, release, sync-issues, and the house style for READMEs, sites and Markdown), from the [falkenslab/falkenslab-plugins](https://github.com/falkenslab/falkenslab-plugins) marketplace. Install them once, for all of Falken's Lab's repositories:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
claude plugin marketplace add falkenslab/falkenslab-plugins
|
|
157
|
+
claude plugin install falkenslab-dev@falkenslab-plugins
|
|
158
|
+
claude plugin install falkenslab-style@falkenslab-plugins
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
<details>
|
|
162
|
+
<summary>What each plugin brings, and what stays in this repository</summary>
|
|
163
|
+
|
|
164
|
+
- 🔧 **falkenslab-dev**: `commit`, `verify`, `update-docs`, `release`, `sync-issues`, `upgrade-deps` and `add-tool`.
|
|
165
|
+
- 🎨 **falkenslab-style**: `falkenslab-docs`, `falkenslab-site-style`, `falkenslab-terminal-screenshots` and `markdown-writing`.
|
|
166
|
+
|
|
167
|
+
Inside Claude Code, the same with `/plugin marketplace add falkenslab/falkenslab-plugins` and `/plugin install falkenslab-dev@falkenslab-plugins`; `/plugin marketplace update falkenslab-plugins` brings their latest version. This repository keeps only the skills that are agent-kit's own, in `.claude/skills/` (`add-export`, the MiniSpec ones and `upgrade-sdk`), and what its release adds to the general one is in [`CLAUDE.md`](./CLAUDE.md#releasing).
|
|
168
|
+
|
|
169
|
+
</details>
|
|
170
|
+
|
|
171
|
+
<div align="center">
|
|
172
|
+
|
|
173
|
+
Made with 💖 by Falken's Lab Team
|
|
174
|
+
|
|
175
|
+
</div>
|
|
@@ -246,6 +246,11 @@ export declare function createChatController(options: Options | SessionOpener, s
|
|
|
246
246
|
* resolved when it ends. An unknown slash command is caught before it reaches the model.
|
|
247
247
|
*/
|
|
248
248
|
send(raw: string): Promise<"exit" | void>;
|
|
249
|
+
/**
|
|
250
|
+
* A turn that doesn't come from the person's keyboard (another agent's, over MCP): the text
|
|
251
|
+
* goes to the agent as it is, never read as one of the chat's commands (`/extensions`, `/resume`).
|
|
252
|
+
*/
|
|
253
|
+
turn(raw: string): Promise<void>;
|
|
249
254
|
/** Stops the turn running, if any. */
|
|
250
255
|
interrupt(): void;
|
|
251
256
|
/** Switches to a mode the session allows; says so when it can't. */
|
|
@@ -493,6 +493,19 @@ export async function createChatController(options, settings = {}) {
|
|
|
493
493
|
}
|
|
494
494
|
await runTurn(line);
|
|
495
495
|
},
|
|
496
|
+
/**
|
|
497
|
+
* A turn that doesn't come from the person's keyboard (another agent's, over MCP): the text
|
|
498
|
+
* goes to the agent as it is, never read as one of the chat's commands (`/extensions`, `/resume`).
|
|
499
|
+
*/
|
|
500
|
+
async turn(raw) {
|
|
501
|
+
const line = raw.trim();
|
|
502
|
+
if (!line)
|
|
503
|
+
return;
|
|
504
|
+
log(`${promptLabel}${line}\n`);
|
|
505
|
+
addEntry({ id: nextId++, kind: "user", text: line });
|
|
506
|
+
emit({ type: "user", text: line });
|
|
507
|
+
await runTurn(line);
|
|
508
|
+
},
|
|
496
509
|
/** Stops the turn running, if any. */
|
|
497
510
|
interrupt() {
|
|
498
511
|
if (!state.busy || interrupted)
|
|
@@ -1,25 +1,57 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
1
|
+
/**
|
|
2
|
+
* The Claude Code binary the Agent SDK ships (`@anthropic-ai/claude-agent-sdk-<platform>-<arch>`),
|
|
3
|
+
* unmodified: the copy unpacked next to the archive when the agent runs packaged, or else the
|
|
4
|
+
* one resolved from `node_modules` as the SDK resolves it. `undefined` when it isn't installed.
|
|
5
|
+
* `resolve` and the platform are replaceable for tests.
|
|
6
|
+
*/
|
|
7
|
+
export declare function claudeExecutable(resolve?: (request: string) => string, platform?: NodeJS.Platform, arch?: string): string | undefined;
|
|
8
|
+
/** What `claudeSignedIn()` and `startClaudeSignIn()` accept. */
|
|
9
|
+
export interface ClaudeAuthOptions {
|
|
10
|
+
/** The binary to run instead of the SDK's own (`claudeExecutable()`); a `.js`/`.mjs` file runs with Node, as the SDK runs one. */
|
|
11
|
+
executable?: string;
|
|
8
12
|
}
|
|
13
|
+
/** The binary and its arguments as a process to spawn: a JavaScript file runs with this Node. */
|
|
14
|
+
export declare function claudeCommand(executable: string, args: string[]): {
|
|
15
|
+
file: string;
|
|
16
|
+
args: string[];
|
|
17
|
+
};
|
|
9
18
|
/**
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
19
|
+
* Whether the agent can reach Claude: true when the person's environment has `ANTHROPIC_API_KEY`
|
|
20
|
+
* or `CLAUDE_CODE_OAUTH_TOKEN` (their own setting); otherwise what the Claude Code binary says
|
|
21
|
+
* (`claude auth status --json`, its `loggedIn`). Never reads the credentials file, and prints
|
|
22
|
+
* nothing: safe from a server or an Electron main process. False when there is no binary.
|
|
23
|
+
*/
|
|
24
|
+
export declare function claudeSignedIn(options?: ClaudeAuthOptions): Promise<boolean>;
|
|
25
|
+
/** A sign-in in progress (`startClaudeSignIn()`): Claude Code's own `auth login`, which keeps the credentials itself. */
|
|
26
|
+
export interface ClaudeSignIn {
|
|
27
|
+
/** Anthropic's sign-in page, to show as a link in case the browser didn't open; `undefined` if the binary ended without printing one. */
|
|
28
|
+
url: Promise<string | undefined>;
|
|
29
|
+
/** The code Anthropic's page shows after signing in, when it shows one: handed to the binary, which waits for it. */
|
|
30
|
+
sendCode(code: string): void;
|
|
31
|
+
/** Once the binary has ended: whether the person is signed in (`claudeSignedIn()`). */
|
|
32
|
+
done: Promise<boolean>;
|
|
33
|
+
/** Stops the sign-in; `done` then resolves with whether the person is signed in anyway. */
|
|
34
|
+
cancel(): void;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Signs the person in to their Claude account through Anthropic's own flow, for a host without a
|
|
38
|
+
* terminal (a web page, a desktop app): runs `claude auth login` (`console: true` for an
|
|
39
|
+
* Anthropic Console account, billed by API usage) with plain pipes. The binary opens the browser
|
|
40
|
+
* itself; the host shows `url` as a link in case it didn't, and a box for the code Anthropic's
|
|
41
|
+
* page shows (`sendCode`). The binary keeps the credentials: the kit never sees a token. Throws
|
|
42
|
+
* when the binary isn't installed.
|
|
13
43
|
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
* `
|
|
23
|
-
*
|
|
44
|
+
* Confirmed empirically (Claude Code 2.1.310): without a TTY, `auth login` prints "If the browser
|
|
45
|
+
* didn't open, visit: <url>" (the URL may come wrapped in OSC 8 hyperlink escapes) and then waits
|
|
46
|
+
* at "Paste code here if prompted >".
|
|
47
|
+
*/
|
|
48
|
+
export declare function startClaudeSignIn(options?: ClaudeAuthOptions & {
|
|
49
|
+
console?: boolean;
|
|
50
|
+
}): ClaudeSignIn;
|
|
51
|
+
/**
|
|
52
|
+
* The sign-in URL in what `claude auth login` printed so far: an OSC 8 hyperlink's target, or a
|
|
53
|
+
* URL in the text with its escapes removed, Anthropic's authorize page (`/oauth/authorize`)
|
|
54
|
+
* first. A URL in the text counts only once whitespace follows it (the rest may still be on its
|
|
55
|
+
* way), unless `complete` says the output is all there is.
|
|
24
56
|
*/
|
|
25
|
-
export declare function
|
|
57
|
+
export declare function signInUrl(output: string, complete?: boolean): string | undefined;
|