@tractorscorch/clank 1.5.10 → 1.7.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.
Files changed (5) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +195 -195
  3. package/dist/index.js +1232 -155
  4. package/dist/index.js.map +1 -1
  5. package/package.json +58 -58
package/CHANGELOG.md CHANGED
@@ -6,6 +6,40 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
6
6
 
7
7
  ---
8
8
 
9
+ ## [1.7.0] — 2026-03-23
10
+
11
+ ### Added
12
+ - **OpenAI Codex OAuth** — sign in with your ChatGPT Plus/Pro account to use Codex models without API costs. Full Authorization Code + PKCE flow with browser-based login, token refresh, and credential storage
13
+ - **`clank auth` commands** — `clank auth login` (OAuth flow), `clank auth status` (show credentials), `clank auth logout` (remove credentials)
14
+ - **OpenCode provider** — subscription-based API at `opencode.ai/zen` with many models
15
+ - **Sub-agent depth control** — configurable `maxSpawnDepth` (default 1) prevents infinite nesting. Depth 0 = main, depth 1+ = sub-agent. Leaf agents cannot spawn further
16
+ - **Sub-agent concurrent limits** — configurable `maxConcurrent` (default 8) prevents resource exhaustion
17
+ - **Task kill/steer/message** — parent agents can kill running tasks (with cascade), restart with new instructions (steer), or send messages to running children
18
+ - **Parent-child task tree** — tasks track their children and parent for full tree visibility
19
+ - **Sub-agent system prompt** — spawned agents are told who spawned them and whether they can spawn further
20
+ - **`task.kill` RPC** — kill tasks from Web UI and TUI
21
+
22
+ ### Changed
23
+ - **Spawn system depth-aware** — any agent within the depth limit can spawn (not just the default agent), enabling orchestrator → worker patterns
24
+
25
+ ---
26
+
27
+ ## [1.6.0] — 2026-03-23
28
+
29
+ ### Added
30
+ - **Multi-provider support** — configure multiple cloud providers (Anthropic, OpenAI, Google, OpenRouter) during setup. Each provider can be assigned to different agents for true multi-model workflows
31
+ - **OpenRouter provider** — access hundreds of models through one API key via OpenRouter's OpenAI-compatible API. Model format: `openrouter/model-name`
32
+ - **Background task system** — main agent can spawn tasks on sub-agents that run independently. `spawn_task` tool with spawn/status/list actions. Results auto-injected into main agent's context when tasks complete
33
+ - **Task registry** — in-memory registry tracks running/completed/failed/timed-out tasks with automatic cleanup
34
+ - **Telegram `/tasks` command** — view background task status from Telegram
35
+ - **`task.list` and `task.status` RPC methods** — task visibility from Web UI and TUI
36
+
37
+ ### Changed
38
+ - **Setup wizard loads existing config** — re-running `clank setup` preserves your existing API keys and settings instead of starting from scratch. Each step shows pre-existing values and lets you keep them
39
+ - **Multi-provider onboarding loop** — setup now lets you add multiple cloud providers in a loop instead of just one
40
+
41
+ ---
42
+
9
43
  ## [1.5.10] — 2026-03-23
10
44
 
11
45
  ### Fixed
package/README.md CHANGED
@@ -1,195 +1,195 @@
1
- <p align="center">
2
- <img src="https://raw.githubusercontent.com/ItsTrag1c/Clank/main/docs/banner.png" alt="Clank" width="100%" />
3
- </p>
4
-
5
- <h1 align="center">Clank</h1>
6
-
7
- <p align="center">
8
- <b>Local-first AI agent gateway.</b> Open-source alternative to OpenClaw, optimized for local models.
9
- </p>
10
-
11
- <p align="center">
12
- <a href="https://github.com/ItsTrag1c/Clank/releases/latest"><img src="https://img.shields.io/badge/version-1.5.10-blue.svg" alt="Version" /></a>
13
- <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License" /></a>
14
- <a href="https://www.npmjs.com/package/@tractorscorch/clank"><img src="https://img.shields.io/npm/v/@tractorscorch/clank.svg" alt="npm" /></a>
15
- <a href="https://github.com/ItsTrag1c/Clank/stargazers"><img src="https://img.shields.io/github/stars/ItsTrag1c/Clank.svg" alt="Stars" /></a>
16
- </p>
17
-
18
- <p align="center">
19
- <a href="https://clanksuite.dev">Website</a> ·
20
- <a href="https://github.com/ItsTrag1c/Clank/blob/main/docs/INSTALL.md">Install Guide</a> ·
21
- <a href="https://github.com/ItsTrag1c/Clank/blob/main/docs/USER_GUIDE.md">User Guide</a> ·
22
- <a href="https://github.com/ItsTrag1c/Clank/blob/main/CHANGELOG.md">Changelog</a> ·
23
- <a href="https://x.com/ClankSuite">Twitter</a> ·
24
- <a href="https://reddit.com/u/ClankSuite">Reddit</a>
25
- </p>
26
-
27
- ---
28
-
29
- ## What is Clank?
30
-
31
- Clank is a personal AI gateway — **one daemon, many frontends**. It connects your preferred interfaces (CLI, TUI, browser, Telegram, Discord) to AI agents running local or cloud models. All interfaces share sessions, memory, and agent state.
32
-
33
- **Built for people who want the OpenClaw experience without the token costs.**
34
-
35
- ```
36
- ┌─────────────────────────────┐
37
- │ Clank Gateway │
38
- │ (single daemon) │
39
- │ │
40
- │ Agent Pool + Routing │
41
- │ Sessions, Memory, Pipelines │
42
- │ Cron, Tools, Plugins │
43
- └──────────────┬───────────────┘
44
- │
45
- WebSocket + HTTP (port 18790)
46
- │
47
- ┌──────────┬───────────┼───────────┬──────────┐
48
- │ │ │ │ │
49
- CLI Web UI Telegram Discord TUI
50
- (direct) (browser) (bot) (bot) (terminal)
51
- ```
52
-
53
- ## Quick Start
54
-
55
- ### npm (all platforms)
56
-
57
- ```bash
58
- npm install -g @tractorscorch/clank
59
- clank setup
60
- clank
61
- ```
62
-
63
- ### macOS (standalone binary)
64
-
65
- ```bash
66
- curl -fsSL https://raw.githubusercontent.com/ItsTrag1c/Clank/main/install.sh | bash
67
- clank setup
68
- clank
69
- ```
70
-
71
- That's it. Setup auto-detects your local models, configures the gateway, and gets you chatting in under 2 minutes. See the [full install guide](docs/INSTALL.md) for details.
72
-
73
- ### Downloads
74
-
75
- | Platform | Download |
76
- |----------|----------|
77
- | **npm** (all platforms) | `npm install -g @tractorscorch/clank` |
78
- | **macOS** (Apple Silicon) | [Clank_1.5.10_macos](https://github.com/ItsTrag1c/Clank/releases/latest/download/Clank_1.5.10_macos) |
79
-
80
- ## Security Notice
81
-
82
- Clank is a **developer tool** that gives AI agents full access to your file system, shell, and connected services. The agent can read, write, and execute on your behalf.
83
-
84
- **We strongly recommend running Clank on dedicated hardware** (a dev machine, VM, or container) rather than on a system with sensitive personal files, credentials, or accounts you don't want the agent to access. Treat it like giving someone SSH access to your box.
85
-
86
- ## Features
87
-
88
- | Feature | Description |
89
- |---------|-------------|
90
- | **Local-first** | Auto-detects Ollama, LM Studio, llama.cpp, vLLM. Cloud providers optional. |
91
- | **Multi-agent** | Named agents with separate models, workspaces, tools, and routing. |
92
- | **Multi-channel** | CLI, TUI, Web UI, Telegram, Discord — all equal, all share sessions. |
93
- | **Self-configuring** | After setup, configure everything through conversation. |
94
- | **18 tools** | File ops, bash, git, web search (Brave), plus 8 self-config tools. |
95
- | **Web Control UI** | 8-panel dashboard: Chat, Agents, Sessions, Config, Pipelines, Cron, Logs, Channels. |
96
- | **Pipeline orchestration** | Chain agents together for multi-step workflows. |
97
- | **Plugin system** | Extend with custom tools, channels, and providers. 25+ hook types. |
98
- | **Cron scheduler** | Recurring and one-shot scheduled agent tasks. |
99
- | **Voice** | Cloud (ElevenLabs) or fully local (whisper.cpp + piper). |
100
- | **Memory** | TF-IDF with decay scoring. Agent learns and remembers across sessions. |
101
- | **Security** | AES-256-GCM encryption, SSRF protection, path containment, config redaction. |
102
-
103
- ## Commands
104
-
105
- ```bash
106
- # Start — gateway + TUI (Telegram/Discord stay alive in background)
107
- clank
108
-
109
- # Chat interfaces
110
- clank chat # Direct mode (no gateway needed)
111
- clank chat --web # Auto-start gateway + open Web UI
112
- clank tui # Rich TUI connected to gateway
113
- clank dashboard # Open Web UI in browser
114
-
115
- # Gateway
116
- clank gateway start # Start in background
117
- clank gateway stop # Stop
118
- clank gateway status # Show status, clients, sessions
119
- clank gateway restart # Restart
120
-
121
- # Setup & diagnostics
122
- clank setup # Onboarding wizard
123
- clank fix # Diagnostics & auto-repair
124
-
125
- # Model & agent management
126
- clank models list # Detect + list models
127
- clank models add # Add a provider (Anthropic, OpenAI, Google, Brave)
128
- clank models test # Test connectivity
129
- clank agents list # List agents
130
- clank agents add # Create an agent
131
-
132
- # Scheduled tasks
133
- clank cron list # List jobs
134
- clank cron add # Schedule a task
135
-
136
- # System
137
- clank daemon install # Auto-start at login (Windows/macOS/Linux)
138
- clank channels # Channel status
139
- clank uninstall # Remove everything
140
- ```
141
-
142
- ## Providers
143
-
144
- | Provider | Type | How |
145
- |----------|------|-----|
146
- | **Ollama** | Local | Auto-detected at `localhost:11434` |
147
- | **LM Studio** | Local | Auto-detected at `localhost:1234` |
148
- | **llama.cpp** | Local | Auto-detected at `localhost:8080` |
149
- | **vLLM** | Local | Auto-detected at `localhost:8000` |
150
- | **Anthropic** | Cloud | API key via `clank setup` or config |
151
- | **OpenAI** | Cloud | API key via `clank setup` or config |
152
- | **Google Gemini** | Cloud | API key via `clank setup` or config |
153
-
154
- Models without native tool calling automatically use prompt-based fallback — tools are injected into the system prompt and parsed from text output.
155
-
156
- ## Security
157
-
158
- Clank is designed to be safe by default:
159
-
160
- - **Workspace containment** — file tools blocked outside workspace
161
- - **Bash protection** — 25-pattern blocklist for destructive commands
162
- - **API key redaction** — keys never sent to LLM context
163
- - **SSRF protection** — web_fetch blocks localhost, cloud metadata, internal hosts
164
- - **Gateway auth** — token-based, auto-generated, localhost-only by default
165
- - **Encryption** — AES-256-GCM for API keys at rest
166
-
167
- See [SECURITY.md](SECURITY.md) for the full security model.
168
-
169
- ## Documentation
170
-
171
- - **[Install Guide](docs/INSTALL.md)** — Detailed installation and setup instructions
172
- - **[User Guide](docs/USER_GUIDE.md)** — How to use Clank day-to-day
173
- - **[Changelog](CHANGELOG.md)** — Version history
174
- - **[Privacy Policy](PRIVACY_POLICY.md)** — Data handling
175
- - **[Security Policy](SECURITY.md)** — Security model and vulnerability reporting
176
-
177
- ## Links
178
-
179
- | | |
180
- |--|--|
181
- | **Website** | [clanksuite.dev](https://clanksuite.dev) |
182
- | **GitHub** | [ItsTrag1c/Clank](https://github.com/ItsTrag1c/Clank) |
183
- | **npm** | [npmjs.com/package/@tractorscorch/clank](https://www.npmjs.com/package/@tractorscorch/clank) |
184
- | **Twitter/X** | [@ClankSuite](https://x.com/ClankSuite) |
185
- | **Reddit** | [u/ClankSuite](https://reddit.com/u/ClankSuite) |
186
- | **Legacy** | [Clank-Legacy](https://github.com/ItsTrag1c/Clank-Legacy) (archived CLI v2.7.0 + Desktop v2.6.1) |
187
-
188
- ## Requirements
189
-
190
- - Node.js 20+
191
- - A local model server (Ollama recommended) or cloud API key
192
-
193
- ## License
194
-
195
- MIT — see [LICENSE](LICENSE)
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/ItsTrag1c/Clank/main/docs/banner.png" alt="Clank" width="100%" />
3
+ </p>
4
+
5
+ <h1 align="center">Clank</h1>
6
+
7
+ <p align="center">
8
+ <b>Local-first AI agent gateway.</b> Open-source alternative to OpenClaw, optimized for local models.
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://github.com/ItsTrag1c/Clank/releases/latest"><img src="https://img.shields.io/badge/version-1.7.0-blue.svg" alt="Version" /></a>
13
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License" /></a>
14
+ <a href="https://www.npmjs.com/package/@tractorscorch/clank"><img src="https://img.shields.io/npm/v/@tractorscorch/clank.svg" alt="npm" /></a>
15
+ <a href="https://github.com/ItsTrag1c/Clank/stargazers"><img src="https://img.shields.io/github/stars/ItsTrag1c/Clank.svg" alt="Stars" /></a>
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="https://clanksuite.dev">Website</a> ·
20
+ <a href="https://github.com/ItsTrag1c/Clank/blob/main/docs/INSTALL.md">Install Guide</a> ·
21
+ <a href="https://github.com/ItsTrag1c/Clank/blob/main/docs/USER_GUIDE.md">User Guide</a> ·
22
+ <a href="https://github.com/ItsTrag1c/Clank/blob/main/CHANGELOG.md">Changelog</a> ·
23
+ <a href="https://x.com/ClankSuite">Twitter</a> ·
24
+ <a href="https://reddit.com/u/ClankSuite">Reddit</a>
25
+ </p>
26
+
27
+ ---
28
+
29
+ ## What is Clank?
30
+
31
+ Clank is a personal AI gateway — **one daemon, many frontends**. It connects your preferred interfaces (CLI, TUI, browser, Telegram, Discord) to AI agents running local or cloud models. All interfaces share sessions, memory, and agent state.
32
+
33
+ **Built for people who want the OpenClaw experience without the token costs.**
34
+
35
+ ```
36
+ ┌─────────────────────────────┐
37
+ │ Clank Gateway │
38
+ │ (single daemon) │
39
+ │ │
40
+ │ Agent Pool + Routing │
41
+ │ Sessions, Memory, Pipelines │
42
+ │ Cron, Tools, Plugins │
43
+ └──────────────┬───────────────┘
44
+ │
45
+ WebSocket + HTTP (port 18790)
46
+ │
47
+ ┌──────────┬───────────┼───────────┬──────────┐
48
+ │ │ │ │ │
49
+ CLI Web UI Telegram Discord TUI
50
+ (direct) (browser) (bot) (bot) (terminal)
51
+ ```
52
+
53
+ ## Quick Start
54
+
55
+ ### npm (all platforms)
56
+
57
+ ```bash
58
+ npm install -g @tractorscorch/clank
59
+ clank setup
60
+ clank
61
+ ```
62
+
63
+ ### macOS (standalone binary)
64
+
65
+ ```bash
66
+ curl -fsSL https://raw.githubusercontent.com/ItsTrag1c/Clank/main/install.sh | bash
67
+ clank setup
68
+ clank
69
+ ```
70
+
71
+ That's it. Setup auto-detects your local models, configures the gateway, and gets you chatting in under 2 minutes. See the [full install guide](docs/INSTALL.md) for details.
72
+
73
+ ### Downloads
74
+
75
+ | Platform | Download |
76
+ |----------|----------|
77
+ | **npm** (all platforms) | `npm install -g @tractorscorch/clank` |
78
+ | **macOS** (Apple Silicon) | [Clank_1.7.0_macos](https://github.com/ItsTrag1c/Clank/releases/latest/download/Clank_1.7.0_macos) |
79
+
80
+ ## Security Notice
81
+
82
+ Clank is a **developer tool** that gives AI agents full access to your file system, shell, and connected services. The agent can read, write, and execute on your behalf.
83
+
84
+ **We strongly recommend running Clank on dedicated hardware** (a dev machine, VM, or container) rather than on a system with sensitive personal files, credentials, or accounts you don't want the agent to access. Treat it like giving someone SSH access to your box.
85
+
86
+ ## Features
87
+
88
+ | Feature | Description |
89
+ |---------|-------------|
90
+ | **Local-first** | Auto-detects Ollama, LM Studio, llama.cpp, vLLM. Cloud providers optional. |
91
+ | **Multi-agent** | Named agents with separate models, workspaces, tools, and routing. |
92
+ | **Multi-channel** | CLI, TUI, Web UI, Telegram, Discord — all equal, all share sessions. |
93
+ | **Self-configuring** | After setup, configure everything through conversation. |
94
+ | **18 tools** | File ops, bash, git, web search (Brave), plus 8 self-config tools. |
95
+ | **Web Control UI** | 8-panel dashboard: Chat, Agents, Sessions, Config, Pipelines, Cron, Logs, Channels. |
96
+ | **Pipeline orchestration** | Chain agents together for multi-step workflows. |
97
+ | **Plugin system** | Extend with custom tools, channels, and providers. 25+ hook types. |
98
+ | **Cron scheduler** | Recurring and one-shot scheduled agent tasks. |
99
+ | **Voice** | Cloud (ElevenLabs) or fully local (whisper.cpp + piper). |
100
+ | **Memory** | TF-IDF with decay scoring. Agent learns and remembers across sessions. |
101
+ | **Security** | AES-256-GCM encryption, SSRF protection, path containment, config redaction. |
102
+
103
+ ## Commands
104
+
105
+ ```bash
106
+ # Start — gateway + TUI (Telegram/Discord stay alive in background)
107
+ clank
108
+
109
+ # Chat interfaces
110
+ clank chat # Direct mode (no gateway needed)
111
+ clank chat --web # Auto-start gateway + open Web UI
112
+ clank tui # Rich TUI connected to gateway
113
+ clank dashboard # Open Web UI in browser
114
+
115
+ # Gateway
116
+ clank gateway start # Start in background
117
+ clank gateway stop # Stop
118
+ clank gateway status # Show status, clients, sessions
119
+ clank gateway restart # Restart
120
+
121
+ # Setup & diagnostics
122
+ clank setup # Onboarding wizard
123
+ clank fix # Diagnostics & auto-repair
124
+
125
+ # Model & agent management
126
+ clank models list # Detect + list models
127
+ clank models add # Add a provider (Anthropic, OpenAI, Google, Brave)
128
+ clank models test # Test connectivity
129
+ clank agents list # List agents
130
+ clank agents add # Create an agent
131
+
132
+ # Scheduled tasks
133
+ clank cron list # List jobs
134
+ clank cron add # Schedule a task
135
+
136
+ # System
137
+ clank daemon install # Auto-start at login (Windows/macOS/Linux)
138
+ clank channels # Channel status
139
+ clank uninstall # Remove everything
140
+ ```
141
+
142
+ ## Providers
143
+
144
+ | Provider | Type | How |
145
+ |----------|------|-----|
146
+ | **Ollama** | Local | Auto-detected at `localhost:11434` |
147
+ | **LM Studio** | Local | Auto-detected at `localhost:1234` |
148
+ | **llama.cpp** | Local | Auto-detected at `localhost:8080` |
149
+ | **vLLM** | Local | Auto-detected at `localhost:8000` |
150
+ | **Anthropic** | Cloud | API key via `clank setup` or config |
151
+ | **OpenAI** | Cloud | API key via `clank setup` or config |
152
+ | **Google Gemini** | Cloud | API key via `clank setup` or config |
153
+
154
+ Models without native tool calling automatically use prompt-based fallback — tools are injected into the system prompt and parsed from text output.
155
+
156
+ ## Security
157
+
158
+ Clank is designed to be safe by default:
159
+
160
+ - **Workspace containment** — file tools blocked outside workspace
161
+ - **Bash protection** — 25-pattern blocklist for destructive commands
162
+ - **API key redaction** — keys never sent to LLM context
163
+ - **SSRF protection** — web_fetch blocks localhost, cloud metadata, internal hosts
164
+ - **Gateway auth** — token-based, auto-generated, localhost-only by default
165
+ - **Encryption** — AES-256-GCM for API keys at rest
166
+
167
+ See [SECURITY.md](SECURITY.md) for the full security model.
168
+
169
+ ## Documentation
170
+
171
+ - **[Install Guide](docs/INSTALL.md)** — Detailed installation and setup instructions
172
+ - **[User Guide](docs/USER_GUIDE.md)** — How to use Clank day-to-day
173
+ - **[Changelog](CHANGELOG.md)** — Version history
174
+ - **[Privacy Policy](PRIVACY_POLICY.md)** — Data handling
175
+ - **[Security Policy](SECURITY.md)** — Security model and vulnerability reporting
176
+
177
+ ## Links
178
+
179
+ | | |
180
+ |--|--|
181
+ | **Website** | [clanksuite.dev](https://clanksuite.dev) |
182
+ | **GitHub** | [ItsTrag1c/Clank](https://github.com/ItsTrag1c/Clank) |
183
+ | **npm** | [npmjs.com/package/@tractorscorch/clank](https://www.npmjs.com/package/@tractorscorch/clank) |
184
+ | **Twitter/X** | [@ClankSuite](https://x.com/ClankSuite) |
185
+ | **Reddit** | [u/ClankSuite](https://reddit.com/u/ClankSuite) |
186
+ | **Legacy** | [Clank-Legacy](https://github.com/ItsTrag1c/Clank-Legacy) (archived CLI v2.7.0 + Desktop v2.6.1) |
187
+
188
+ ## Requirements
189
+
190
+ - Node.js 20+
191
+ - A local model server (Ollama recommended) or cloud API key
192
+
193
+ ## License
194
+
195
+ MIT — see [LICENSE](LICENSE)