@clagentic/console 1.4.1 → 1.5.0-beta.2
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 +90 -21
- package/bin/cli.js +170 -60
- package/deploy/clagentic-console.service +2 -0
- package/lib/agents-favorites.js +3 -1
- package/lib/agents.js +75 -5
- package/lib/audit.js +23 -2
- package/lib/browser-mcp-server.js +5 -5
- package/lib/clone-validate.js +44 -0
- package/lib/config.js +175 -2
- package/lib/daemon.js +115 -9
- package/lib/dm.js +12 -1
- package/lib/ipc.js +12 -0
- package/lib/lite-detect.js +92 -0
- package/lib/os-users.js +8 -8
- package/lib/project-connection.js +7 -1
- package/lib/project-external-trigger.js +65 -6
- package/lib/project-loop.js +44 -3
- package/lib/project-sessions.js +95 -37
- package/lib/project.js +6 -1
- package/lib/public/app.js +6 -3
- package/lib/public/css/at-agents.css +68 -0
- package/lib/public/index.html +60 -0
- package/lib/public/modules/app-messages.js +38 -4
- package/lib/public/modules/at-agents.js +248 -0
- package/lib/public/modules/escape-html.js +19 -0
- package/lib/public/modules/filebrowser.js +12 -9
- package/lib/public/modules/input.js +26 -4
- package/lib/public/modules/pending-navigate.js +28 -0
- package/lib/public/modules/playbook.js +1 -1
- package/lib/public/modules/project-settings.js +75 -0
- package/lib/public/modules/project-switcher.js +1 -1
- package/lib/public/modules/server-settings.js +33 -0
- package/lib/public/modules/sticky-notes-fmt.js +52 -0
- package/lib/public/modules/sticky-notes.js +23 -5
- package/lib/public/modules/theme.js +1 -1
- package/lib/public/modules/tool-palette.js +1 -1
- package/lib/public/modules/utils.js +1 -3
- package/lib/public/style.css +1 -0
- package/lib/push.js +13 -2
- package/lib/scheduler.js +26 -2
- package/lib/sdk-bridge.js +7 -4
- package/lib/server-admin.js +1 -1
- package/lib/server-dm.js +16 -0
- package/lib/server-settings.js +42 -0
- package/lib/server-skills.js +10 -7
- package/lib/server.js +14 -3
- package/lib/sessions.js +4 -0
- package/lib/ws-schema.js +11 -1
- package/lib/yoke/adapters/claude-worker.js +2 -2
- package/lib/yoke/adapters/claude.js +47 -10
- package/lib/yoke/adapters/codex.js +14 -3
- package/lib/yoke/mcp-bridge-server.js +7 -7
- package/package.json +3 -2
- package/lib/relay-agent-claims.js +0 -480
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="media/logo/console-lockup-256.png" alt="
|
|
2
|
+
<img src="media/logo/console-lockup-256.png" alt="Clagentic: Console" width="260" />
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<h4 align="center">AI tooling. Built for builders.</h4>
|
|
@@ -13,9 +13,7 @@
|
|
|
13
13
|
<a href="https://ko-fi.com/clagentic"><img src="https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat&logo=ko-fi&logoColor=white&label=support" alt="Support on Ko-fi" /></a>
|
|
14
14
|
</p>
|
|
15
15
|
|
|
16
|
-
A self-hosted
|
|
17
|
-
|
|
18
|
-
No extras bolted on. No opinionated workflows. The floor is solid; you build what you need on top.
|
|
16
|
+
A self-hosted control plane for your AI runtimes. Clagentic: Console runs as a daemon on your machine and serves a full browser and mobile interface to Claude Code and ChatGPT Codex. Every project, every session, every tool approval — reachable from any device, all data staying on disk.
|
|
19
17
|
|
|
20
18
|
## Install
|
|
21
19
|
|
|
@@ -23,13 +21,13 @@ No extras bolted on. No opinionated workflows. The floor is solid; you build wha
|
|
|
23
21
|
npm install -g @clagentic/console
|
|
24
22
|
```
|
|
25
23
|
|
|
26
|
-
Then
|
|
24
|
+
Then start the daemon:
|
|
27
25
|
|
|
28
26
|
```bash
|
|
29
27
|
clagentic-console
|
|
30
28
|
```
|
|
31
29
|
|
|
32
|
-
Or try
|
|
30
|
+
Or try without installing:
|
|
33
31
|
|
|
34
32
|
```bash
|
|
35
33
|
npx @clagentic/console
|
|
@@ -37,19 +35,45 @@ npx @clagentic/console
|
|
|
37
35
|
|
|
38
36
|
**Requirements:** Node.js 20+. Authenticated Claude Code CLI, Codex CLI, or both.
|
|
39
37
|
|
|
38
|
+
### Postinstall / systemd
|
|
39
|
+
|
|
40
|
+
On Linux, a global npm install runs a postinstall script that registers and enables a `clagentic-console.service` systemd unit. The script never restarts an already-running daemon — active sessions are not interrupted. Self-updates triggered from inside the app skip the restart entirely and let systemd's `Restart=always` handle the handoff after graceful shutdown.
|
|
41
|
+
|
|
42
|
+
To skip the postinstall script:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm install -g @clagentic/console --ignore-scripts
|
|
46
|
+
```
|
|
47
|
+
|
|
40
48
|
## What it does
|
|
41
49
|
|
|
42
|
-
- **
|
|
43
|
-
|
|
44
|
-
- **
|
|
45
|
-
|
|
46
|
-
- **Loop automation.** Write a `PROMPT.md`,
|
|
47
|
-
|
|
50
|
+
- **Named agent sessions.** Type `@` in the session input to launch any agent defined in `.claude/agents/` or `~/.claude/agents/` into its own session — with its own conversation history, context window, and state. Pick agents by name, switch mid-conversation.
|
|
51
|
+
|
|
52
|
+
- **Context injection.** Pin running terminals, live browser tabs, and sticky notes as active context sources. Their content flows into every message automatically: terminal output as a delta since your last message, browser tabs as full snapshots. No manual copy-paste. No extra prompting.
|
|
53
|
+
|
|
54
|
+
- **Loop automation.** Write a `PROMPT.md`, start a loop. Clagentic: Console runs the prompt, evaluates the result, and retries until done or capped. Schedule loops with standard cron syntax to run unattended.
|
|
55
|
+
|
|
56
|
+
- **External triggers.** Drop a JSON file into `~/.clagentic/external-triggers/` to spawn a new AI session or inject a message into an existing one. Use this to wire Claude into scripts, CI pipelines, or other AI processes — no API, no polling, just a file drop.
|
|
57
|
+
|
|
58
|
+
- **Cross-vendor instruction injection.** YOKE (the vendor adapter layer) scans `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `COPILOT.md`, and `.github/copilot-instructions.md` and cross-injects whichever ones the active vendor doesn't read natively. Switch from Claude to Codex in a session — your project instructions still reach the model.
|
|
59
|
+
|
|
60
|
+
- **Multi-project dashboard.** Every repo registered with the daemon in one sidebar. Jump between projects, run sessions in parallel, see live status at a glance.
|
|
61
|
+
|
|
62
|
+
- **Mobile PWA + push notifications.** Installable on iOS and Android. Approve tool calls from your phone. Push fires on approval requests, errors, and task completion.
|
|
63
|
+
|
|
64
|
+
- **Multi-user with OS isolation.** On Linux, opt in: each user maps to a real system account, file ACLs via `setfacl`, processes spawn under the correct UID/GID.
|
|
65
|
+
|
|
66
|
+
- **Vendor flexibility.** Claude Code (Claude Agent SDK) and ChatGPT Codex (codex app-server protocol). Switch per session. Sessions remember their vendor.
|
|
67
|
+
|
|
68
|
+
- **MCP servers.** Built-in ask-user and browser servers. User-configured MCPs via `~/.clagentic/mcp.json`. Works in both Claude and Codex sessions.
|
|
69
|
+
|
|
48
70
|
- **Your data, your machine.** Sessions are JSONL, settings are JSON, knowledge is Markdown. No cloud relay, no proprietary database.
|
|
49
71
|
|
|
72
|
+
- **Clagentic: Lite (optional).** If [Clagentic: Lite](https://clagentic.ai/tools) is installed, project settings surface per-project enrollment controls and system settings add a global auto-enroll toggle. Console detects it passively — nothing changes if it isn't present.
|
|
73
|
+
|
|
50
74
|
## Getting Started
|
|
51
75
|
|
|
52
|
-
On first run you'll be asked for a port and
|
|
76
|
+
On first run you'll be asked for a port and prompted to create your admin account. Open the URL from any device on your network.
|
|
53
77
|
|
|
54
78
|
For remote access, use a tunnel — Tailscale, Cloudflare Tunnel, or your existing VPN.
|
|
55
79
|
|
|
@@ -71,7 +95,7 @@ Also available as `clagentic-console` if installed globally.
|
|
|
71
95
|
|
|
72
96
|
## Architecture
|
|
73
97
|
|
|
74
|
-
Clagentic:Console is a self-hosted daemon. It drives Claude Code via the Claude Agent SDK and Codex via the `codex app-server` JSON-RPC protocol through a vendor-agnostic adapter layer (YOKE), and serves a multi-user web workspace over HTTP/WS. Sessions and settings live as plain JSONL/JSON/Markdown on disk.
|
|
98
|
+
Clagentic: Console is a self-hosted daemon. It drives Claude Code via the Claude Agent SDK and Codex via the `codex app-server` JSON-RPC protocol through a vendor-agnostic adapter layer (YOKE), and serves a multi-user web workspace over HTTP/WS. Sessions and settings live as plain JSONL/JSON/Markdown on disk.
|
|
75
99
|
|
|
76
100
|
```mermaid
|
|
77
101
|
graph LR
|
|
@@ -81,7 +105,7 @@ graph LR
|
|
|
81
105
|
Phone["Phone PWA + Push"]
|
|
82
106
|
end
|
|
83
107
|
|
|
84
|
-
subgraph Daemon["Clagentic:Console Daemon (your machine)"]
|
|
108
|
+
subgraph Daemon["Clagentic: Console Daemon (your machine)"]
|
|
85
109
|
Auth["Auth + RBAC"]
|
|
86
110
|
Server["HTTP / WS Server"]
|
|
87
111
|
Project["Project Context"]
|
|
@@ -110,18 +134,60 @@ graph LR
|
|
|
110
134
|
|
|
111
135
|
For architecture details, sequence diagrams, and key design decisions, see [docs/guides/architecture.md](docs/guides/architecture.md).
|
|
112
136
|
|
|
137
|
+
## Security
|
|
138
|
+
|
|
139
|
+
These are implementation-level properties, not configuration options — they apply to every installation.
|
|
140
|
+
|
|
141
|
+
- **Token TTL.** Multi-user auth tokens expire after 30 days (`TOKEN_TTL_MS`). Tokens issued before TTL support was added are migrated on first use to a fresh 30-day window, avoiding forced logouts on upgrade.
|
|
142
|
+
|
|
143
|
+
- **Atomic writes, mode 0o600.** All config and state files (`users.json`, `auth-tokens.json`, and similar) are written via rename-after-write: data goes to a `.tmp.<pid>` path, then `rename()` atomically replaces the target. After rename, `chmod 0o600` is applied. Concurrent writes to the same file are serialized in call order.
|
|
144
|
+
|
|
145
|
+
- **Append-only audit log.** Privileged actions — user creation, lockouts, token revocation, multi-user enable/disable — are written as newline-delimited JSON to `~/.clagentic/audit.log` (mode 0o600, opened with `O_APPEND`).
|
|
146
|
+
|
|
147
|
+
- **Progressive lockout.** Failed login attempts trigger escalating per-username backoff: 1s, 5s, 30s, 5 min. Reaching the threshold results in permanent lockout until an admin explicitly unlocks the account. Per-IP rate limiting runs in parallel.
|
|
148
|
+
|
|
149
|
+
- **OS-level isolation (Linux, multi-user mode).** Each app user maps to a real system account. File ACLs are set via `setfacl`; processes spawn under the correct UID/GID.
|
|
150
|
+
|
|
151
|
+
## Testing
|
|
152
|
+
|
|
153
|
+
The test suite covers 12 areas across 26 test files:
|
|
154
|
+
|
|
155
|
+
- **Boot / smoke** — daemon startup, config bootstrap, guard checks
|
|
156
|
+
- **Security gates** — auth token TTL, lockout thresholds, PIN rate limiting, audit log entries
|
|
157
|
+
- **WebSocket permission gates** — per-user RBAC enforcement on WS message types
|
|
158
|
+
- **Session lifecycle** — session open, resume, shutdown, and reaper behavior
|
|
159
|
+
- **External triggers** — v1 and v2 trigger processing, file archival, restart survival
|
|
160
|
+
- **Scheduler** — cron parsing, loop execution, run accounting
|
|
161
|
+
- **Store atomicity** — concurrent write serialization, atomic rename, 0o600 mode
|
|
162
|
+
- **XSS escaping** — output sanitization for user-controlled strings rendered in HTML
|
|
163
|
+
- **YOKE robustness** — vendor adapter error handling and fallback paths
|
|
164
|
+
- **SDK bridge** — slot counter, message processor, slash command enrichment, workflow and skill discovery, worker shutdown
|
|
165
|
+
- **Replay** — session replay correctness
|
|
166
|
+
- **ESM import check** — verifies the package is importable as an ES module
|
|
167
|
+
|
|
168
|
+
Run the suite: `npm test`
|
|
169
|
+
|
|
113
170
|
## FAQ
|
|
114
171
|
|
|
115
172
|
**"Is this a Claude Code wrapper?"**
|
|
116
|
-
No. Clagentic:Console drives Claude Code through the Claude Agent SDK and Codex through the Codex app-server protocol. It adds multi-session orchestration, named agent sessions, scheduled agents, multi-user support, built-in MCP servers, and a full browser UI on top.
|
|
173
|
+
No. Clagentic: Console drives Claude Code through the Claude Agent SDK and Codex through the Codex app-server protocol. It adds multi-session orchestration, named agent sessions, scheduled agents, multi-user support, built-in MCP servers, context injection, external triggers, and a full browser UI on top.
|
|
117
174
|
|
|
118
175
|
**"What are named agents?"**
|
|
119
|
-
Agents defined in your Claude Code config (`.claude/agents/`) become first-class sessions.
|
|
176
|
+
Agents defined in your Claude Code config (`.claude/agents/` or `~/.claude/agents/`) become first-class sessions. Type `@` in the session input to see every installed agent and launch one directly — its own conversation history, context window, and session state.
|
|
120
177
|
|
|
121
|
-
Named agents are **currently Claude Code only.** The Codex adapter has no equivalent API for per-session agent identity injection
|
|
178
|
+
Named agents are **currently Claude Code only.** The Codex adapter has no equivalent API for per-session agent identity injection. When you're in a Codex session, the agent entry point is hidden. Partial Codex parity (system-prompt prepend) is planned.
|
|
179
|
+
|
|
180
|
+
**"How does context injection work?"**
|
|
181
|
+
Open the Context panel in the session input area. Pin a running terminal, a browser tab (requires the Clagentic: Console Chrome extension), or a sticky note. From that point on, every message you send automatically includes the latest content from those sources — terminal output as a delta since the last message, browser tabs as a full page snapshot. The injection happens before your message reaches the model; you don't need to mention the sources in your prompt.
|
|
182
|
+
|
|
183
|
+
**"What's the external trigger system?"**
|
|
184
|
+
Drop a JSON file into `~/.clagentic/external-triggers/`. The daemon picks it up within seconds. A v1 trigger spawns a new session with an `initialPrompt`. A v2 trigger can either spawn a session or inject a message into an existing session by `sessionId`. The file is archived to `processed/` on success. Unprocessed files survive daemon restarts. Use this to wire Claude into scripts, CI pipelines, cron jobs, or other AI processes.
|
|
185
|
+
|
|
186
|
+
**"What instruction files does it read?"**
|
|
187
|
+
YOKE scans the project directory for `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `COPILOT.md`, and `.github/copilot-instructions.md`. Each vendor reads some of these natively — Claude reads `CLAUDE.md`, Codex reads `AGENTS.md`. Files the active vendor doesn't read natively are merged and injected as additional context, so your project instructions reach the model regardless of which vendor is running.
|
|
122
188
|
|
|
123
189
|
**"Is feature parity between Claude Code and Codex complete?"**
|
|
124
|
-
Not yet.
|
|
190
|
+
Not yet. Named agents are the main gap — the Claude Agent SDK exposes agent identity injection directly; Codex does not. Claude Code has been the primary development target. Codex support covers sessions, tool approvals, model selection, MCP servers, loop, and most UI surfaces. Features that depend on Claude Agent SDK internals have no Codex equivalent today.
|
|
125
191
|
|
|
126
192
|
**"Can I run Claude Code and Codex in the same workspace?"**
|
|
127
193
|
Yes. Pick a vendor when you open a session. Switch per session — sessions remember their vendor.
|
|
@@ -130,7 +196,7 @@ Yes. Pick a vendor when you open a session. Switch per session — sessions reme
|
|
|
130
196
|
Only as model API calls — the same as using the CLI directly. Sessions, settings, and knowledge all stay on disk.
|
|
131
197
|
|
|
132
198
|
**"Does my existing CLAUDE.md / AGENTS.md work?"**
|
|
133
|
-
Yes. Native instruction files are loaded per vendor and merged automatically.
|
|
199
|
+
Yes. Native instruction files are loaded per vendor and merged automatically. Non-native files are cross-injected by YOKE.
|
|
134
200
|
|
|
135
201
|
**"Can I continue a CLI session in the browser?"**
|
|
136
202
|
Yes. CLI sessions appear in the sidebar and can be picked up in the CLI.
|
|
@@ -144,9 +210,12 @@ Yes. User-configured MCPs from `~/.clagentic/mcp.json` plus built-in ask-user an
|
|
|
144
210
|
**"Multi-user support?"**
|
|
145
211
|
Yes. On Linux, opt in to OS-level isolation: each user maps to a real Linux account, file ACLs via `setfacl`, processes spawn under the correct UID/GID.
|
|
146
212
|
|
|
213
|
+
**"Does it integrate with Clagentic: Lite?"**
|
|
214
|
+
Yes, optionally. [Clagentic: Lite](https://clagentic.ai/tools) adds agentic gates, session memory, and audit trails to any repo. If Lite is installed (`~/.clagentic/lite/`), Console detects it automatically and shows an enrollment panel in each project's settings. Enable auto-enroll in system settings to wire up every project on add. Lite is never required — Console works normally without it.
|
|
215
|
+
|
|
147
216
|
## Support
|
|
148
217
|
|
|
149
|
-
If
|
|
218
|
+
If Clagentic: Console is useful to you: [ko-fi.com/clagentic](https://ko-fi.com/clagentic)
|
|
150
219
|
|
|
151
220
|
## Credits
|
|
152
221
|
|