@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.
Files changed (54) hide show
  1. package/README.md +90 -21
  2. package/bin/cli.js +170 -60
  3. package/deploy/clagentic-console.service +2 -0
  4. package/lib/agents-favorites.js +3 -1
  5. package/lib/agents.js +75 -5
  6. package/lib/audit.js +23 -2
  7. package/lib/browser-mcp-server.js +5 -5
  8. package/lib/clone-validate.js +44 -0
  9. package/lib/config.js +175 -2
  10. package/lib/daemon.js +115 -9
  11. package/lib/dm.js +12 -1
  12. package/lib/ipc.js +12 -0
  13. package/lib/lite-detect.js +92 -0
  14. package/lib/os-users.js +8 -8
  15. package/lib/project-connection.js +7 -1
  16. package/lib/project-external-trigger.js +65 -6
  17. package/lib/project-loop.js +44 -3
  18. package/lib/project-sessions.js +95 -37
  19. package/lib/project.js +6 -1
  20. package/lib/public/app.js +6 -3
  21. package/lib/public/css/at-agents.css +68 -0
  22. package/lib/public/index.html +60 -0
  23. package/lib/public/modules/app-messages.js +38 -4
  24. package/lib/public/modules/at-agents.js +248 -0
  25. package/lib/public/modules/escape-html.js +19 -0
  26. package/lib/public/modules/filebrowser.js +12 -9
  27. package/lib/public/modules/input.js +26 -4
  28. package/lib/public/modules/pending-navigate.js +28 -0
  29. package/lib/public/modules/playbook.js +1 -1
  30. package/lib/public/modules/project-settings.js +75 -0
  31. package/lib/public/modules/project-switcher.js +1 -1
  32. package/lib/public/modules/server-settings.js +33 -0
  33. package/lib/public/modules/sticky-notes-fmt.js +52 -0
  34. package/lib/public/modules/sticky-notes.js +23 -5
  35. package/lib/public/modules/theme.js +1 -1
  36. package/lib/public/modules/tool-palette.js +1 -1
  37. package/lib/public/modules/utils.js +1 -3
  38. package/lib/public/style.css +1 -0
  39. package/lib/push.js +13 -2
  40. package/lib/scheduler.js +26 -2
  41. package/lib/sdk-bridge.js +7 -4
  42. package/lib/server-admin.js +1 -1
  43. package/lib/server-dm.js +16 -0
  44. package/lib/server-settings.js +42 -0
  45. package/lib/server-skills.js +10 -7
  46. package/lib/server.js +14 -3
  47. package/lib/sessions.js +4 -0
  48. package/lib/ws-schema.js +11 -1
  49. package/lib/yoke/adapters/claude-worker.js +2 -2
  50. package/lib/yoke/adapters/claude.js +47 -10
  51. package/lib/yoke/adapters/codex.js +14 -3
  52. package/lib/yoke/mcp-bridge-server.js +7 -7
  53. package/package.json +3 -2
  54. 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="clagentic:console" width="260" />
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 browser console for Claude Code and ChatGPT Codex. Part of the [clagentic](https://clagentic.ai) suite. Run AI sessions from any browser or phone — tool approvals, model selection, context management, session history — without leaving your own machine.
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 run from anywhere:
24
+ Then start the daemon:
27
25
 
28
26
  ```bash
29
27
  clagentic-console
30
28
  ```
31
29
 
32
- Or try it without installing:
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
- - **Browser access to your AI runtimes.** The goal is full parity with the CLI for both Claude Code and Codex — tool approvals, model selection, context management, session history. Most things work; see the FAQ for current gaps.
43
- - **Named agent sessions (Claude Code).** Talk directly to any agent defined in your Claude Code config. Agents get their own sessions, context, and history. This feature is currently Claude Code only — see FAQ for details and what's planned for Codex.
44
- - **Multi-project dashboard.** Every repo on your machine in one sidebar. Jump between projects, run sessions in parallel, see live status at a glance.
45
- - **Mobile PWA + push notifications.** Installable on iOS and Android. Your phone buzzes when Claude needs approval or finishes a long task — tap to respond from anywhere.
46
- - **Loop automation.** Write a `PROMPT.md`, hit go. Clagentic:Console iterates: run, evaluate, retry until done or capped. Schedule with standard cron.
47
- - **Vendor flexibility.** Supports Claude Code (Claude Agent SDK) and ChatGPT Codex (codex app-server protocol). Switch per session.
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 whether you're running solo or multi-user. Open the URL from any device on your network.
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. You talk to them directly — their own conversation history, context window, and session state.
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 — the Claude Agent SDK exposes this directly, Codex does not. When you're in a Codex session, the Agent Chat entry point is hidden automatically. Partial Codex parity (system-prompt prepend) is planned; until then, agents only apply when the session vendor is Claude Code.
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. The goal is full parity, but there are gaps. Named agents (above) are the main one. 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 (agent identity, extended thinking, some beta flags) have no Codex equivalent today.
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 clagentic:console is useful to you: [ko-fi.com/clagentic](https://ko-fi.com/clagentic)
218
+ If Clagentic: Console is useful to you: [ko-fi.com/clagentic](https://ko-fi.com/clagentic)
150
219
 
151
220
  ## Credits
152
221