local-commander-agent 0.3.49 → 0.3.51
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/CHANGELOG.md +12 -1
- package/README.md +216 -216
- package/bin/localcommander.mjs +3 -1
- package/bin/monitor-context.d.mts +7 -7
- package/bin/monitor-savings.d.mts +20 -20
- package/package.json +4 -4
- package/runtime/JobHost.exe +0 -0
- package/runtime/LocalCommanderAgent.exe +0 -0
- package/runtime/OwnerBridge.exe +0 -0
- package/runtime/agent.mjs +380 -249
package/CHANGELOG.md
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
# Change history
|
|
2
2
|
|
|
3
|
+
## 0.3.51 - 2026-10-23
|
|
4
|
+
|
|
5
|
+
- Show a native informational notice when the account owner enables or disables full logs for this computer.
|
|
6
|
+
- Include the authenticated full-log choice in local status; stale or disconnected state is shown as unknown.
|
|
7
|
+
- Preserve notification deduplication across reconnects and restarts without changing logging consent.
|
|
8
|
+
|
|
9
|
+
## 0.3.50 - 2026-10-23
|
|
10
|
+
|
|
11
|
+
- Fixed: a computer paused because its identity changed (for example after a rename or a disk copy) now waits instead of stopping. After you click Trust at localcmd.app it reconnects within about a minute, with no restart.
|
|
12
|
+
- Includes everything in 0.3.49.
|
|
13
|
+
|
|
3
14
|
## 0.3.49 - 2026-10-23
|
|
4
15
|
|
|
5
16
|
- Commands without an explicit working folder no longer block file work across the approved drive. Specify cwd when folder serialization is needed.
|
|
6
|
-
- Work held by another task in the same folder
|
|
17
|
+
- Work held by another task in the same folder is refused after 20 seconds instead of disappearing behind a relay timeout. Nothing ran; retry after the other task finishes. Public asynchronous polling currently reports PRE_ACCEPTANCE_REJECTED for this refusal.
|
|
7
18
|
- Includes everything in 0.3.48.
|
|
8
19
|
|
|
9
20
|
## 0.3.48 - 2026-10-22
|
package/README.md
CHANGED
|
@@ -1,216 +1,216 @@
|
|
|
1
|
-
# Local Commander Agent
|
|
2
|
-
|
|
3
|
-
**Connect your AI assistant to your computer through [Local Commander](https://localcmd.app).** The agent lets an authorized MCP client work with local files, run explicitly approved commands, and access approved localhost services on your paired computer.
|
|
4
|
-
|
|
5
|
-
> **Requires the Local Commander service at https://localcmd.app.** This npm package is its computer companion, not a standalone MCP server, an offline AI assistant, or a JavaScript SDK. Installing the package alone is not enough: you need a Local Commander account, an approved device pairing, a running agent, an internet connection, and an authorized MCP connection from your AI client. Local management commands such as status and stop do not require the service to be online.
|
|
6
|
-
|
|
7
|
-
[Website and sign-in](https://localcmd.app) ┬╖ [Support](https://localcmd.app/support) ┬╖ [Privacy](https://localcmd.app/privacy)
|
|
8
|
-
|
|
9
|
-
## Before you start
|
|
10
|
-
|
|
11
|
-
Use **Windows 11 x64**, **macOS 14 or later on Apple Silicon**, or **Linux with a systemd user session** (Ubuntu 24.04 x64 or arm64), and a currently supported Node.js LTS version meeting the package's Node.js 20+ minimum. Node.js/npm are needed to launch `npx`; the installed background agent includes its own Node runtime. You do not need Docker, WSL, a repository checkout, a database, or administrator rights for normal setup. Your AI client must support authenticated remote MCP connections; availability depends on the client and workspace policy.
|
|
12
|
-
|
|
13
|
-
## Install and connect
|
|
14
|
-
|
|
15
|
-
1. Open a terminal as your normal user (PowerShell or Windows Terminal on Windows, Terminal on macOS or Linux) and run:
|
|
16
|
-
|
|
17
|
-
```powershell
|
|
18
|
-
npx local-commander-agent@latest
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
2. The installer opens a browser. Sign in to [Local Commander](https://localcmd.app), check the displayed pairing code, and approve this computer. Approve only a pairing you just started yourself.
|
|
22
|
-
3. Choose access in the local window (on Windows and macOS; Linux asks one question in the terminal):
|
|
23
|
-
- **Full access - all connected drives (default):** approve the available drive letters, file reads/writes, installed commands and localhost services at once. There is no folder picker or separate approval for Node.
|
|
24
|
-
- **Selected folders:** choose one folder in the folder picker. It starts read/write; more folders and write permission can be added later.
|
|
25
|
-
|
|
26
|
-
Cancel leaves existing permissions unchanged. On first setup, cancellation stops before enabling autostart or starting the agent. Existing grants are preserved when repeating installation or updating: an update never opts you into all drives.
|
|
27
|
-
4. After the terminal reports that Local Commander is installed and running, connect your AI client to the remote MCP endpoint:
|
|
28
|
-
|
|
29
|
-
```text
|
|
30
|
-
https://localcmd.app/mcp
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
Complete the browser authorization with the same Local Commander account. Device pairing and AI-client authorization are separate steps. For an AI client that runs on this same computer, you can instead use direct local MCP (see "Direct local MCP" below). Do not configure `npx local-commander-agent` itself as a stdio server.
|
|
34
|
-
|
|
35
|
-
You can close the installation terminal. The agent runs in the background and starts when you sign in to this computer. The computer must be awake and online for remote AI tasks. As a first test, ask the connected assistant to list the files in a folder you approved.
|
|
36
|
-
|
|
37
|
-
On Windows, installation and update also add `localcommander` to your **user PATH**. Open a new CMD/terminal window, then run `localcommander status`, `localcommander monitor --watch`, or `localcommander logs --follow` from any folder. No global npm installation is needed. The launcher uses your required Node.js installation and an installed copy of the CLI, so clearing npm's cache does not remove the command. Fetch newer releases with `npx local-commander-agent@latest update`. Uninstall removes Local Commander's PATH entry and launcher while preserving your other entries.
|
|
38
|
-
|
|
39
|
-
## Direct local MCP (AI clients on this computer)
|
|
40
|
-
|
|
41
|
-
An AI client that runs on the same computer, such as Claude Code, Codex or Cursor, can use your approved workspaces directly through the running agent. No cloud round trip happens per call. It keeps working while the internet or localcmd.app is unavailable, and calls take milliseconds instead of a cloud admission. Hosted assistants such as ChatGPT or claude.ai on the web still use `https://localcmd.app/mcp`.
|
|
42
|
-
|
|
43
|
-
1. Turn it on once. This is an owner choice for this user account, and `off` revokes it immediately:
|
|
44
|
-
|
|
45
|
-
```powershell
|
|
46
|
-
localcommander mcp on
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
2. Add Local Commander as a stdio MCP server in the client:
|
|
50
|
-
|
|
51
|
-
```text
|
|
52
|
-
Claude Code: claude mcp add local-commander -- cmd /c localcommander mcp
|
|
53
|
-
Codex: ~/.codex/config.toml
|
|
54
|
-
[mcp_servers.local-commander]
|
|
55
|
-
command = "cmd"
|
|
56
|
-
args = ["/c", "localcommander", "mcp"]
|
|
57
|
-
Other clients: { "command": "cmd", "args": ["/c", "localcommander", "mcp"] }
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
The tools are the same as the remote ones: `workspace_list`, file reads and writes, search, Git, `project_snapshot`, `command_run` and `localhost_request`. Each takes an optional `workspace` (a grant id, a root such as `D:\`, or a display name). The same workspace grants, Full Access or scoped mode and owner denials apply, and commands run hidden with your user account's rights.
|
|
61
|
-
|
|
62
|
-
The agent listens only on `127.0.0.1`, and only while direct local MCP is on. Every connection must first prove a key that only this user's protected Local Commander state can derive, so other users and other computers cannot connect. Check the state with `localcommander mcp status`; turn it off with `localcommander mcp off`. While an enterprise Guard policy is configured, direct local calls are refused so that Guard evidence cannot be bypassed.
|
|
63
|
-
|
|
64
|
-
## What тАЬall connected drivesтАЭ means
|
|
65
|
-
|
|
66
|
-
It expands the **filesystem scope** to the drive letters shown at the moment you consent. It includes available local fixed and removable drives. Mapped network drives and `subst` letters are not included. New drive letters, unavailable drives and unmounted volumes are not automatically added; run `configure-access` again after making the desired drive available. Grants are path/drive-letter based, not tied to a particular removable disk's hardware identity: reusing an approved letter gives access under that letter.
|
|
67
|
-
|
|
68
|
-
Full access allows installed commands resolved from absolute owner PATH entries or an absolute executable path, plus localhost services. Explicit command/port denials and write restrictions still apply. It does not elevate privileges. Protected Local Commander state/runtime and secret-file filters apply to file tools; programs run with your user account's rights, so these controls are not an OS sandbox. ChatGPT/Claude or your workspace may still ask for their own action confirmations. Existing installations keep their current permissions until the owner runs `configure-access` and selects full access using a release that supports it.
|
|
69
|
-
|
|
70
|
-
## Manage the installation
|
|
71
|
-
|
|
72
|
-
```powershell
|
|
73
|
-
npx local-commander-agent@latest status
|
|
74
|
-
npx local-commander-agent@latest start
|
|
75
|
-
npx local-commander-agent@latest stop
|
|
76
|
-
npx local-commander-agent@latest restart
|
|
77
|
-
npx local-commander-agent@latest update
|
|
78
|
-
npx local-commander-agent@latest uninstall
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
`status` reports the local installed version, process and pairing state; it is not proof of a healthy cloud relay connection. Installation files and per-user state live under `%LOCALAPPDATA%\LocalCommander`. Updating preserves enrollment and permissions. Close or finish active AI tasks before restarting or updating.
|
|
82
|
-
|
|
83
|
-
Normal uninstall preserves protected enrollment state for reinstallation. To also remove this computer's local enrollment and permissions:
|
|
84
|
-
|
|
85
|
-
```powershell
|
|
86
|
-
npx local-commander-agent@latest uninstall --purge-state
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
Uninstall never deletes your project folders. For a lost or untrusted computer, also revoke its access through your Local Commander account; removing local files is not a substitute for cloud revocation.
|
|
90
|
-
|
|
91
|
-
## Change access later
|
|
92
|
-
|
|
93
|
-
Run these commands yourself on the paired computer. Install the release containing these commands with `update` before using them on an older installation.
|
|
94
|
-
|
|
95
|
-
```powershell
|
|
96
|
-
npx local-commander-agent@latest configure-access
|
|
97
|
-
npx local-commander-agent@latest approve-workspace
|
|
98
|
-
npx local-commander-agent@latest workspaces
|
|
99
|
-
npx local-commander-agent@latest revoke-workspace <workspaceGrantId>
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
`configure-access` reopens the full-access/selected-folder choice. **It replaces the current set of grants and their restrictions.** Full access enables commands and localhost by default; selected folders start read/write with separate command/port allowlists. Choosing a restricted folder removes old broader grants. `approve-workspace` adds another read/write folder without replacing the existing set. `workspaces` shows grant IDs, full/scoped mode and explicit denials. A successful change restarts an already-running agent to synchronize grants; cancellation does not restart it. A revoked drive is not silently re-added in the background.
|
|
103
|
-
|
|
104
|
-
To enable or remove individual capabilities, replace the placeholders with a grant ID from `workspaces` and an executable path that actually exists on your PC:
|
|
105
|
-
|
|
106
|
-
```powershell
|
|
107
|
-
npx local-commander-agent@latest allow-write <workspaceGrantId>
|
|
108
|
-
npx local-commander-agent@latest allow-command <workspaceGrantId> node "C:\Program Files\nodejs\node.exe"
|
|
109
|
-
npx local-commander-agent@latest allow-localhost <workspaceGrantId> 3000
|
|
110
|
-
|
|
111
|
-
npx local-commander-agent@latest deny-write <workspaceGrantId>
|
|
112
|
-
npx local-commander-agent@latest deny-command <workspaceGrantId> node
|
|
113
|
-
npx local-commander-agent@latest deny-localhost <workspaceGrantId> 3000
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
`allow-command` associates an exact executable with the name the assistant uses; it does not accept a shell command string. Capability changes are local owner actions, not MCP settings the assistant can silently widen. The all-drives decision always requires the local dialog; there is no `--yes` or environment flag to approve it.
|
|
117
|
-
|
|
118
|
-
### Scoped access: approve Git from CMD or PowerShell
|
|
119
|
-
|
|
120
|
-
When giving an owner Windows commands, identify the shell before using shell-specific syntax and label the example. Prefer explicit workspace IDs and quoted absolute executable paths that work in both CMD and PowerShell; do not assume a standard installation path.
|
|
121
|
-
|
|
122
|
-
Use the example for the shell you are running. A prompt such as `C:\project>` is normally **Command Prompt (CMD)**; `PS C:\project>` is normally **PowerShell**. Windows Terminal can host either shell.
|
|
123
|
-
|
|
124
|
-
For selected-folders/scoped mode, first run `npx local-commander-agent@latest workspaces` and copy the intended workspace's grant ID. Full Access does not require this setup for Git.
|
|
125
|
-
|
|
126
|
-
**CMD:** run `where git.exe`. If it lists several paths, choose the Git executable you intend to approve. Replace `WORKSPACE_ID` and the example path below with those actual values; keep the path in double quotes.
|
|
127
|
-
|
|
128
|
-
```cmd
|
|
129
|
-
where git.exe
|
|
130
|
-
npx local-commander-agent@latest allow-command WORKSPACE_ID git "C:\Path To Git\git.exe"
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
**PowerShell:** replace `WORKSPACE_ID` with the grant ID. This selects the first Git executable found on PATH and passes its path as one argument. Inspect the other matches with `Get-Command git.exe -CommandType Application` if you intend to approve a different installation. `npx.cmd` explicitly selects npm's batch launcher.
|
|
134
|
-
|
|
135
|
-
```powershell
|
|
136
|
-
$gitExe = @(Get-Command git.exe -CommandType Application -ErrorAction Stop)[0].Source
|
|
137
|
-
npx.cmd local-commander-agent@latest allow-command WORKSPACE_ID git "$gitExe"
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
Do not paste `(Get-Command git).Source` into CMD: CMD passes it literally instead of resolving an executable. Local Commander accepts a path, never evaluates a shell expression, and still requires the local owner confirmation. If lookup finds no Git executable, stop and locate the installed program before approving it.
|
|
141
|
-
|
|
142
|
-
`allow-command --help` shows these instructions without requiring an installed agent or opening a permission dialog. Malformed arguments keep the `ARGUMENT_INVALID` error and nonzero exit status, followed by usage and shell-specific guidance. Diagnostic output does not repeat the supplied arguments. These diagnostics require a release containing this fix; editing the documentation does not update an installed CLI.
|
|
143
|
-
|
|
144
|
-
Under full access, `deny-command` and `deny-localhost` exclude the named command or port while other commands/ports remain available. Native `.exe`/`.com` commands receive argument arrays directly. `.cmd`/`.bat` launchers use a hidden PowerShell wrapper and reject cmd metacharacters in arguments; use an explicit interpreter for more complex scripts. Allowing a general interpreter is not containment against it launching a denied program.
|
|
145
|
-
|
|
146
|
-
Under **owner-approved Full Access**, installed Windows shells, script hosts and administration executables (including PowerShell and CMD) work without per-command registration. They execute under the user account's own rights, not elevated privileges. Owner-defined `deny-command` exclusions and explicit write/localhost restrictions still apply. A general interpreter can access resources beyond file-tool path checks; Full Access is not an OS sandbox. Existing scoped grants stay scoped until the owner deliberately changes access with `configure-access`.
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
For a remote MCP client with an unknown device/workspace, use `workspace_list`, then `execution_session_open`, perform the requested work and read results. Reuse valid, already authorized session and target context where supported. `diagnostics` is for faults, not a mandatory startup roundtrip. Diagnostics reports quota separately from the device's execution slot limit. Its optional `repairSafe` mode releases only expired reservations from this OAuth connection that never acquired a dispatch lease. It never retries work, changes permissions or clears unknown executions.
|
|
150
|
-
|
|
151
|
-
## Troubleshooting
|
|
152
|
-
|
|
153
|
-
| Symptom | What to check |
|
|
154
|
-
| --- | --- |
|
|
155
|
-
| `npx` is not recognized | Install supported Node.js LTS, then open a new terminal. |
|
|
156
|
-
| Unsupported OS or architecture | Supported: Windows 11 x64, macOS 14 or later on Apple Silicon, Linux x64 or arm64 with systemd. Windows ARM64 and Intel Macs are not supported. |
|
|
157
|
-
| Pairing does not complete | Open https://localcmd.app, verify your account and internet access, then rerun the install command to resume. Do not share pairing codes. |
|
|
158
|
-
| `ACCESS_SETUP_CANCELLED` | No filesystem grant was saved by that dialog. Rerun setup and choose the intended scope. |
|
|
159
|
-
| `STATE_CHANGED` | Local account/policy/permissions changed while the dialog was open. Review current state and reopen the dialog. |
|
|
160
|
-
| `WORKSPACE_INVALID` | Choose an existing ordinary folder, not a link or protected state directory. Use the all-drives choice for drive roots. |
|
|
161
|
-
| `LOCAL_PERMISSION_REQUIRED` | Inspect `workspaces`; enable only the exact write/command/localhost capability needed. |
|
|
162
|
-
| `ARGUMENT_INVALID` from `allow-command` | Supply the workspace ID, command name and one quoted absolute executable path. Use `where git.exe` in CMD or `Get-Command git.exe` in PowerShell; see the shell-specific examples above and `allow-command --help`. |
|
|
163
|
-
| `PATH_NOT_ALLOWED` | The target is outside the grant, resolves elsewhere through a link, or is protected. Do not bypass the boundary with another tool. |
|
|
164
|
-
| Paired and running, but the AI cannot reach the PC | Check that the PC is awake/online and that the AI client's remote MCP connection is authorized to the same account. Check service status/support. |
|
|
165
|
-
|
|
166
|
-
For help, use [Local Commander support](https://localcmd.app/support) or email [peter.mamrukov@localcmd.app](mailto:peter.mamrukov@localcmd.app). Share error codes and the installed version, not keys, tokens, pairing codes, private state files or unredacted logs.
|
|
167
|
-
|
|
168
|
-
## Operator-only: a different control plane
|
|
169
|
-
|
|
170
|
-
Normal customers should not change the service origin. An operator testing a compatible staging or self-hosted **complete Local Commander service** may set the origin before first pairing:
|
|
171
|
-
|
|
172
|
-
```powershell
|
|
173
|
-
$env:LC_CONTROL_PLANE_ORIGIN = "https://your-control-plane.example"
|
|
174
|
-
npx local-commander-agent@latest
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
Enrollment retains the chosen origin. Changing this variable does not move an already paired device or turn the package into a standalone MCP server. Account/device enrollment, OAuth, the control plane and relay are still required.
|
|
178
|
-
|
|
179
|
-
## Monitor the production connection from CMD
|
|
180
|
-
|
|
181
|
-
After installing an agent release with monitoring support, run these commands from any CMD window:
|
|
182
|
-
|
|
183
|
-
```cmd
|
|
184
|
-
npx local-commander-agent@latest monitor
|
|
185
|
-
npx local-commander-agent@latest monitor --watch
|
|
186
|
-
npx local-commander-agent@latest logs --follow
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
If the CLI is already on PATH, use `localcommander monitor --watch` or `localcommander logs --follow`. `monitor --json` returns a machine-readable snapshot; `logs` prints recent events once. Ctrl+C exits a live view without stopping the agent. These commands only read local monitoring files; they do not install, pair, restart, dispatch cloud work or consume execution quota.
|
|
190
|
-
|
|
191
|
-
The live view also reads registered runtime presence from the current project's `.local-commander/agents.json` and native workers from the configured agent state's `.local-commander/fabric/mailbox.json`. It observes live local `codex`, `claude` and `cursor-agent` processes through hidden bounded Windows process metadata reads. It shows reporting agents and observed hosts even while they have no active Local Commander command; unused registrations and empty activity rows do not receive named screen rows. Host display IDs are stable eight-character hashes of computer/name/PID/start time; they are process observations, not server-issued AI identities. CPU activity describes measured local CPU use; waiting on a provider or thinking is not inferred.
|
|
192
|
-
|
|
193
|
-
Reported task activity, confirmed worker model attribution and confirmed execution IDs are used when available. Linked commands appear beneath their agents; only measured savings from those exact linked executions contribute to an agent row. Unlinked host model/savings remain unavailable. A `+` on an agent savings figure marks partial retained execution coverage. The last finished command remains visible with its completion time, so short commands do not disappear between refreshes. `--json` includes all bounded agent/host rows, including those omitted for screen size. A missing/denied/corrupt presence source is isolated and reported as unavailable; the monitor never initializes or mutates those registries and never reads capabilities, credentials or private chat histories. Current commands use bounded redacted previews emitted by the tool runtime.
|
|
194
|
-
|
|
195
|
-
The navy/cyan ASCII view groups requested/prepared/accepted/running processes beneath each computer. Each populated row shows a reported agent/host name or eight-character work ID, actual child PID when available, command summary, declared model and estimated tokens saved. Columns account for Unicode display width; blank rows have no generated names. Connected idle computers show READY. The fixed footer reports Raw/Sent/Saved token estimates and savings percentage from measured output bytes for this run; partial totals are marked when some companions have older snapshots. Completed, rejected, unknown, stale and stopped executions stay out of this screen. Freshness follows authenticated transport activity when the relay advertises monitorHeartbeatV1; three missed negotiated heartbeat intervals mark it stale. Fresh local writes cannot renew transport proof. Older peers/snapshots retain the ten-second rule. Work IDs identify executions; sessions are not AI instance identities. Only computers with snapshots available locally can appear.
|
|
196
|
-
|
|
197
|
-
In a terminal, `monitor --watch` uses a fixed screen and rewrites only changed lines every two seconds. Computers and work IDs have stable ordering; the footer stays at the bottom as processes start and finish. It fits the terminal size, repaints on resize and reports omitted active processes. It does not scroll or clear/redraw on each refresh; Ctrl+C restores the terminal, colors and cursor. One-shot `monitor` prints the same active-work view; redirected watch output and `--json` are ordinary snapshots. `NO_COLOR=1` disables colors; terminal backgrounds use the sample's navy with cyan status highlights.
|
|
198
|
-
|
|
199
|
-
The first-use MCP greeting asks which model you use when unknown; approved work continues without an answer. The client can classify each batch with optional `efficiencyProfile: {model: "your-model"}`. Labels are declarations, never verified AI identity or permissions. Repeat the label on each batch; missing metadata stays unknown. No pricing is collected or calculated.
|
|
200
|
-
|
|
201
|
-
Savings use the existing output-compaction ledger: original/sent bytes are measured, and estimated saved tokens equal saved bytes divided by four. The monitor totals cover this agent run, grouped by declared model, and reset on restart. They are not provider token counts. Older snapshots show unavailable savings rather than a fabricated zero.
|
|
202
|
-
|
|
203
|
-
The runtime reuses its last 64 shaped terminal results for later completed output reads, so repeated reads match the counted compacted result. The encrypted journal retains the original output. After restart or result-cache eviction, reads fall back to that original output; no historical model attribution or extra savings is invented.
|
|
204
|
-
|
|
205
|
-
Each instance retains its last 64 observed executions, 100 events, 32 sessions and up to 32 model groups in `%LOCALAPPDATA%\LocalCommander\Monitor`. Legacy command classes remain compatible; optional previews show actual executable and simple arguments (24 arguments, 240 characters maximum). Inline scripts, credential flags/paths, headers, message bodies and other payload arguments are redacted. Execution result code, timeout, elapsed time and sanitized working directory provide context without retaining tool output. Child PIDs are runtime notifications; the companion PID is identified separately.
|
|
206
|
-
|
|
207
|
-
`logs` shows recent events, model/command classifications and measured compaction or passthrough sizes. Its initial review lists the five largest remaining outputs and suggests focused file reads/searches, lower command verbosity or less polling when the observed counts justify it. These are advisory review candidates, not proven avoidable tokens, automatic command changes or caching. `logs --follow` reports overwritten-history gaps. Last snapshots remain inspectable after a stop, and a new run replaces that state directory's snapshot. `monitor --json` includes all bounded observations, including finished work omitted from the live screen.
|
|
208
|
-
|
|
209
|
-
An older installed agent produces no monitoring snapshot even if it is running; the CLI reports that monitoring is unavailable. Publishing/installing the updated agent is required before these views can report its connection. The existing `status` command remains available for installation and process state.
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
### Monitor measurements and release history
|
|
213
|
-
|
|
214
|
-
The view shows measured per-agent calls, mean tool-plus-queue duration, stdout bytes, sent response bytes and errors when an identified reporter has those counters. Native measured calls, status/output polls and session records are separate figures; sessions are not execution capacity. Current savings totals exclude stale native snapshots. Missing measurements remain unavailable.
|
|
215
|
-
|
|
216
|
-
Release changes are listed in `CHANGELOG.md`, which ships with this package (npm **Code** tab).
|
|
1
|
+
# Local Commander Agent
|
|
2
|
+
|
|
3
|
+
**Connect your AI assistant to your computer through [Local Commander](https://localcmd.app).** The agent lets an authorized MCP client work with local files, run explicitly approved commands, and access approved localhost services on your paired computer.
|
|
4
|
+
|
|
5
|
+
> **Requires the Local Commander service at https://localcmd.app.** This npm package is its computer companion, not a standalone MCP server, an offline AI assistant, or a JavaScript SDK. Installing the package alone is not enough: you need a Local Commander account, an approved device pairing, a running agent, an internet connection, and an authorized MCP connection from your AI client. Local management commands such as status and stop do not require the service to be online.
|
|
6
|
+
|
|
7
|
+
[Website and sign-in](https://localcmd.app) ┬╖ [Support](https://localcmd.app/support) ┬╖ [Privacy](https://localcmd.app/privacy)
|
|
8
|
+
|
|
9
|
+
## Before you start
|
|
10
|
+
|
|
11
|
+
Use **Windows 11 x64**, **macOS 14 or later on Apple Silicon**, or **Linux with a systemd user session** (Ubuntu 24.04 x64 or arm64), and a currently supported Node.js LTS version meeting the package's Node.js 20+ minimum. Node.js/npm are needed to launch `npx`; the installed background agent includes its own Node runtime. You do not need Docker, WSL, a repository checkout, a database, or administrator rights for normal setup. Your AI client must support authenticated remote MCP connections; availability depends on the client and workspace policy.
|
|
12
|
+
|
|
13
|
+
## Install and connect
|
|
14
|
+
|
|
15
|
+
1. Open a terminal as your normal user (PowerShell or Windows Terminal on Windows, Terminal on macOS or Linux) and run:
|
|
16
|
+
|
|
17
|
+
```powershell
|
|
18
|
+
npx local-commander-agent@latest
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
2. The installer opens a browser. Sign in to [Local Commander](https://localcmd.app), check the displayed pairing code, and approve this computer. Approve only a pairing you just started yourself.
|
|
22
|
+
3. Choose access in the local window (on Windows and macOS; Linux asks one question in the terminal):
|
|
23
|
+
- **Full access - all connected drives (default):** approve the available drive letters, file reads/writes, installed commands and localhost services at once. There is no folder picker or separate approval for Node.
|
|
24
|
+
- **Selected folders:** choose one folder in the folder picker. It starts read/write; more folders and write permission can be added later.
|
|
25
|
+
|
|
26
|
+
Cancel leaves existing permissions unchanged. On first setup, cancellation stops before enabling autostart or starting the agent. Existing grants are preserved when repeating installation or updating: an update never opts you into all drives.
|
|
27
|
+
4. After the terminal reports that Local Commander is installed and running, connect your AI client to the remote MCP endpoint:
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
https://localcmd.app/mcp
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Complete the browser authorization with the same Local Commander account. Device pairing and AI-client authorization are separate steps. For an AI client that runs on this same computer, you can instead use direct local MCP (see "Direct local MCP" below). Do not configure `npx local-commander-agent` itself as a stdio server.
|
|
34
|
+
|
|
35
|
+
You can close the installation terminal. The agent runs in the background and starts when you sign in to this computer. The computer must be awake and online for remote AI tasks. As a first test, ask the connected assistant to list the files in a folder you approved.
|
|
36
|
+
|
|
37
|
+
On Windows, installation and update also add `localcommander` to your **user PATH**. Open a new CMD/terminal window, then run `localcommander status`, `localcommander monitor --watch`, or `localcommander logs --follow` from any folder. No global npm installation is needed. The launcher uses your required Node.js installation and an installed copy of the CLI, so clearing npm's cache does not remove the command. Fetch newer releases with `npx local-commander-agent@latest update`. Uninstall removes Local Commander's PATH entry and launcher while preserving your other entries.
|
|
38
|
+
|
|
39
|
+
## Direct local MCP (AI clients on this computer)
|
|
40
|
+
|
|
41
|
+
An AI client that runs on the same computer, such as Claude Code, Codex or Cursor, can use your approved workspaces directly through the running agent. No cloud round trip happens per call. It keeps working while the internet or localcmd.app is unavailable, and calls take milliseconds instead of a cloud admission. Hosted assistants such as ChatGPT or claude.ai on the web still use `https://localcmd.app/mcp`.
|
|
42
|
+
|
|
43
|
+
1. Turn it on once. This is an owner choice for this user account, and `off` revokes it immediately:
|
|
44
|
+
|
|
45
|
+
```powershell
|
|
46
|
+
localcommander mcp on
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
2. Add Local Commander as a stdio MCP server in the client:
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
Claude Code: claude mcp add local-commander -- cmd /c localcommander mcp
|
|
53
|
+
Codex: ~/.codex/config.toml
|
|
54
|
+
[mcp_servers.local-commander]
|
|
55
|
+
command = "cmd"
|
|
56
|
+
args = ["/c", "localcommander", "mcp"]
|
|
57
|
+
Other clients: { "command": "cmd", "args": ["/c", "localcommander", "mcp"] }
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The tools are the same as the remote ones: `workspace_list`, file reads and writes, search, Git, `project_snapshot`, `command_run` and `localhost_request`. Each takes an optional `workspace` (a grant id, a root such as `D:\`, or a display name). The same workspace grants, Full Access or scoped mode and owner denials apply, and commands run hidden with your user account's rights.
|
|
61
|
+
|
|
62
|
+
The agent listens only on `127.0.0.1`, and only while direct local MCP is on. Every connection must first prove a key that only this user's protected Local Commander state can derive, so other users and other computers cannot connect. Check the state with `localcommander mcp status`; turn it off with `localcommander mcp off`. While an enterprise Guard policy is configured, direct local calls are refused so that Guard evidence cannot be bypassed.
|
|
63
|
+
|
|
64
|
+
## What тАЬall connected drivesтАЭ means
|
|
65
|
+
|
|
66
|
+
It expands the **filesystem scope** to the drive letters shown at the moment you consent. It includes available local fixed and removable drives. Mapped network drives and `subst` letters are not included. New drive letters, unavailable drives and unmounted volumes are not automatically added; run `configure-access` again after making the desired drive available. Grants are path/drive-letter based, not tied to a particular removable disk's hardware identity: reusing an approved letter gives access under that letter.
|
|
67
|
+
|
|
68
|
+
Full access allows installed commands resolved from absolute owner PATH entries or an absolute executable path, plus localhost services. Explicit command/port denials and write restrictions still apply. It does not elevate privileges. Protected Local Commander state/runtime and secret-file filters apply to file tools; programs run with your user account's rights, so these controls are not an OS sandbox. ChatGPT/Claude or your workspace may still ask for their own action confirmations. Existing installations keep their current permissions until the owner runs `configure-access` and selects full access using a release that supports it.
|
|
69
|
+
|
|
70
|
+
## Manage the installation
|
|
71
|
+
|
|
72
|
+
```powershell
|
|
73
|
+
npx local-commander-agent@latest status
|
|
74
|
+
npx local-commander-agent@latest start
|
|
75
|
+
npx local-commander-agent@latest stop
|
|
76
|
+
npx local-commander-agent@latest restart
|
|
77
|
+
npx local-commander-agent@latest update
|
|
78
|
+
npx local-commander-agent@latest uninstall
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`status` reports the local installed version, process and pairing state; it is not proof of a healthy cloud relay connection. Installation files and per-user state live under `%LOCALAPPDATA%\LocalCommander`. Updating preserves enrollment and permissions. Close or finish active AI tasks before restarting or updating.
|
|
82
|
+
|
|
83
|
+
Normal uninstall preserves protected enrollment state for reinstallation. To also remove this computer's local enrollment and permissions:
|
|
84
|
+
|
|
85
|
+
```powershell
|
|
86
|
+
npx local-commander-agent@latest uninstall --purge-state
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Uninstall never deletes your project folders. For a lost or untrusted computer, also revoke its access through your Local Commander account; removing local files is not a substitute for cloud revocation.
|
|
90
|
+
|
|
91
|
+
## Change access later
|
|
92
|
+
|
|
93
|
+
Run these commands yourself on the paired computer. Install the release containing these commands with `update` before using them on an older installation.
|
|
94
|
+
|
|
95
|
+
```powershell
|
|
96
|
+
npx local-commander-agent@latest configure-access
|
|
97
|
+
npx local-commander-agent@latest approve-workspace
|
|
98
|
+
npx local-commander-agent@latest workspaces
|
|
99
|
+
npx local-commander-agent@latest revoke-workspace <workspaceGrantId>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`configure-access` reopens the full-access/selected-folder choice. **It replaces the current set of grants and their restrictions.** Full access enables commands and localhost by default; selected folders start read/write with separate command/port allowlists. Choosing a restricted folder removes old broader grants. `approve-workspace` adds another read/write folder without replacing the existing set. `workspaces` shows grant IDs, full/scoped mode and explicit denials. A successful change restarts an already-running agent to synchronize grants; cancellation does not restart it. A revoked drive is not silently re-added in the background.
|
|
103
|
+
|
|
104
|
+
To enable or remove individual capabilities, replace the placeholders with a grant ID from `workspaces` and an executable path that actually exists on your PC:
|
|
105
|
+
|
|
106
|
+
```powershell
|
|
107
|
+
npx local-commander-agent@latest allow-write <workspaceGrantId>
|
|
108
|
+
npx local-commander-agent@latest allow-command <workspaceGrantId> node "C:\Program Files\nodejs\node.exe"
|
|
109
|
+
npx local-commander-agent@latest allow-localhost <workspaceGrantId> 3000
|
|
110
|
+
|
|
111
|
+
npx local-commander-agent@latest deny-write <workspaceGrantId>
|
|
112
|
+
npx local-commander-agent@latest deny-command <workspaceGrantId> node
|
|
113
|
+
npx local-commander-agent@latest deny-localhost <workspaceGrantId> 3000
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
`allow-command` associates an exact executable with the name the assistant uses; it does not accept a shell command string. Capability changes are local owner actions, not MCP settings the assistant can silently widen. The all-drives decision always requires the local dialog; there is no `--yes` or environment flag to approve it.
|
|
117
|
+
|
|
118
|
+
### Scoped access: approve Git from CMD or PowerShell
|
|
119
|
+
|
|
120
|
+
When giving an owner Windows commands, identify the shell before using shell-specific syntax and label the example. Prefer explicit workspace IDs and quoted absolute executable paths that work in both CMD and PowerShell; do not assume a standard installation path.
|
|
121
|
+
|
|
122
|
+
Use the example for the shell you are running. A prompt such as `C:\project>` is normally **Command Prompt (CMD)**; `PS C:\project>` is normally **PowerShell**. Windows Terminal can host either shell.
|
|
123
|
+
|
|
124
|
+
For selected-folders/scoped mode, first run `npx local-commander-agent@latest workspaces` and copy the intended workspace's grant ID. Full Access does not require this setup for Git.
|
|
125
|
+
|
|
126
|
+
**CMD:** run `where git.exe`. If it lists several paths, choose the Git executable you intend to approve. Replace `WORKSPACE_ID` and the example path below with those actual values; keep the path in double quotes.
|
|
127
|
+
|
|
128
|
+
```cmd
|
|
129
|
+
where git.exe
|
|
130
|
+
npx local-commander-agent@latest allow-command WORKSPACE_ID git "C:\Path To Git\git.exe"
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
**PowerShell:** replace `WORKSPACE_ID` with the grant ID. This selects the first Git executable found on PATH and passes its path as one argument. Inspect the other matches with `Get-Command git.exe -CommandType Application` if you intend to approve a different installation. `npx.cmd` explicitly selects npm's batch launcher.
|
|
134
|
+
|
|
135
|
+
```powershell
|
|
136
|
+
$gitExe = @(Get-Command git.exe -CommandType Application -ErrorAction Stop)[0].Source
|
|
137
|
+
npx.cmd local-commander-agent@latest allow-command WORKSPACE_ID git "$gitExe"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Do not paste `(Get-Command git).Source` into CMD: CMD passes it literally instead of resolving an executable. Local Commander accepts a path, never evaluates a shell expression, and still requires the local owner confirmation. If lookup finds no Git executable, stop and locate the installed program before approving it.
|
|
141
|
+
|
|
142
|
+
`allow-command --help` shows these instructions without requiring an installed agent or opening a permission dialog. Malformed arguments keep the `ARGUMENT_INVALID` error and nonzero exit status, followed by usage and shell-specific guidance. Diagnostic output does not repeat the supplied arguments. These diagnostics require a release containing this fix; editing the documentation does not update an installed CLI.
|
|
143
|
+
|
|
144
|
+
Under full access, `deny-command` and `deny-localhost` exclude the named command or port while other commands/ports remain available. Native `.exe`/`.com` commands receive argument arrays directly. `.cmd`/`.bat` launchers use a hidden PowerShell wrapper and reject cmd metacharacters in arguments; use an explicit interpreter for more complex scripts. Allowing a general interpreter is not containment against it launching a denied program.
|
|
145
|
+
|
|
146
|
+
Under **owner-approved Full Access**, installed Windows shells, script hosts and administration executables (including PowerShell and CMD) work without per-command registration. They execute under the user account's own rights, not elevated privileges. Owner-defined `deny-command` exclusions and explicit write/localhost restrictions still apply. A general interpreter can access resources beyond file-tool path checks; Full Access is not an OS sandbox. Existing scoped grants stay scoped until the owner deliberately changes access with `configure-access`.
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
For a remote MCP client with an unknown device/workspace, use `workspace_list`, then `execution_session_open`, perform the requested work and read results. Reuse valid, already authorized session and target context where supported. `diagnostics` is for faults, not a mandatory startup roundtrip. Diagnostics reports quota separately from the device's execution slot limit. Its optional `repairSafe` mode releases only expired reservations from this OAuth connection that never acquired a dispatch lease. It never retries work, changes permissions or clears unknown executions.
|
|
150
|
+
|
|
151
|
+
## Troubleshooting
|
|
152
|
+
|
|
153
|
+
| Symptom | What to check |
|
|
154
|
+
| --- | --- |
|
|
155
|
+
| `npx` is not recognized | Install supported Node.js LTS, then open a new terminal. |
|
|
156
|
+
| Unsupported OS or architecture | Supported: Windows 11 x64, macOS 14 or later on Apple Silicon, Linux x64 or arm64 with systemd. Windows ARM64 and Intel Macs are not supported. |
|
|
157
|
+
| Pairing does not complete | Open https://localcmd.app, verify your account and internet access, then rerun the install command to resume. Do not share pairing codes. |
|
|
158
|
+
| `ACCESS_SETUP_CANCELLED` | No filesystem grant was saved by that dialog. Rerun setup and choose the intended scope. |
|
|
159
|
+
| `STATE_CHANGED` | Local account/policy/permissions changed while the dialog was open. Review current state and reopen the dialog. |
|
|
160
|
+
| `WORKSPACE_INVALID` | Choose an existing ordinary folder, not a link or protected state directory. Use the all-drives choice for drive roots. |
|
|
161
|
+
| `LOCAL_PERMISSION_REQUIRED` | Inspect `workspaces`; enable only the exact write/command/localhost capability needed. |
|
|
162
|
+
| `ARGUMENT_INVALID` from `allow-command` | Supply the workspace ID, command name and one quoted absolute executable path. Use `where git.exe` in CMD or `Get-Command git.exe` in PowerShell; see the shell-specific examples above and `allow-command --help`. |
|
|
163
|
+
| `PATH_NOT_ALLOWED` | The target is outside the grant, resolves elsewhere through a link, or is protected. Do not bypass the boundary with another tool. |
|
|
164
|
+
| Paired and running, but the AI cannot reach the PC | Check that the PC is awake/online and that the AI client's remote MCP connection is authorized to the same account. Check service status/support. |
|
|
165
|
+
|
|
166
|
+
For help, use [Local Commander support](https://localcmd.app/support) or email [peter.mamrukov@localcmd.app](mailto:peter.mamrukov@localcmd.app). Share error codes and the installed version, not keys, tokens, pairing codes, private state files or unredacted logs.
|
|
167
|
+
|
|
168
|
+
## Operator-only: a different control plane
|
|
169
|
+
|
|
170
|
+
Normal customers should not change the service origin. An operator testing a compatible staging or self-hosted **complete Local Commander service** may set the origin before first pairing:
|
|
171
|
+
|
|
172
|
+
```powershell
|
|
173
|
+
$env:LC_CONTROL_PLANE_ORIGIN = "https://your-control-plane.example"
|
|
174
|
+
npx local-commander-agent@latest
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Enrollment retains the chosen origin. Changing this variable does not move an already paired device or turn the package into a standalone MCP server. Account/device enrollment, OAuth, the control plane and relay are still required.
|
|
178
|
+
|
|
179
|
+
## Monitor the production connection from CMD
|
|
180
|
+
|
|
181
|
+
After installing an agent release with monitoring support, run these commands from any CMD window:
|
|
182
|
+
|
|
183
|
+
```cmd
|
|
184
|
+
npx local-commander-agent@latest monitor
|
|
185
|
+
npx local-commander-agent@latest monitor --watch
|
|
186
|
+
npx local-commander-agent@latest logs --follow
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
If the CLI is already on PATH, use `localcommander monitor --watch` or `localcommander logs --follow`. `monitor --json` returns a machine-readable snapshot; `logs` prints recent events once. Ctrl+C exits a live view without stopping the agent. These commands only read local monitoring files; they do not install, pair, restart, dispatch cloud work or consume execution quota.
|
|
190
|
+
|
|
191
|
+
The live view also reads registered runtime presence from the current project's `.local-commander/agents.json` and native workers from the configured agent state's `.local-commander/fabric/mailbox.json`. It observes live local `codex`, `claude` and `cursor-agent` processes through hidden bounded Windows process metadata reads. It shows reporting agents and observed hosts even while they have no active Local Commander command; unused registrations and empty activity rows do not receive named screen rows. Host display IDs are stable eight-character hashes of computer/name/PID/start time; they are process observations, not server-issued AI identities. CPU activity describes measured local CPU use; waiting on a provider or thinking is not inferred.
|
|
192
|
+
|
|
193
|
+
Reported task activity, confirmed worker model attribution and confirmed execution IDs are used when available. Linked commands appear beneath their agents; only measured savings from those exact linked executions contribute to an agent row. Unlinked host model/savings remain unavailable. A `+` on an agent savings figure marks partial retained execution coverage. The last finished command remains visible with its completion time, so short commands do not disappear between refreshes. `--json` includes all bounded agent/host rows, including those omitted for screen size. A missing/denied/corrupt presence source is isolated and reported as unavailable; the monitor never initializes or mutates those registries and never reads capabilities, credentials or private chat histories. Current commands use bounded redacted previews emitted by the tool runtime.
|
|
194
|
+
|
|
195
|
+
The navy/cyan ASCII view groups requested/prepared/accepted/running processes beneath each computer. Each populated row shows a reported agent/host name or eight-character work ID, actual child PID when available, command summary, declared model and estimated tokens saved. Columns account for Unicode display width; blank rows have no generated names. Connected idle computers show READY. The fixed footer reports Raw/Sent/Saved token estimates and savings percentage from measured output bytes for this run; partial totals are marked when some companions have older snapshots. Completed, rejected, unknown, stale and stopped executions stay out of this screen. Freshness follows authenticated transport activity when the relay advertises monitorHeartbeatV1; three missed negotiated heartbeat intervals mark it stale. Fresh local writes cannot renew transport proof. Older peers/snapshots retain the ten-second rule. Work IDs identify executions; sessions are not AI instance identities. Only computers with snapshots available locally can appear.
|
|
196
|
+
|
|
197
|
+
In a terminal, `monitor --watch` uses a fixed screen and rewrites only changed lines every two seconds. Computers and work IDs have stable ordering; the footer stays at the bottom as processes start and finish. It fits the terminal size, repaints on resize and reports omitted active processes. It does not scroll or clear/redraw on each refresh; Ctrl+C restores the terminal, colors and cursor. One-shot `monitor` prints the same active-work view; redirected watch output and `--json` are ordinary snapshots. `NO_COLOR=1` disables colors; terminal backgrounds use the sample's navy with cyan status highlights.
|
|
198
|
+
|
|
199
|
+
The first-use MCP greeting asks which model you use when unknown; approved work continues without an answer. The client can classify each batch with optional `efficiencyProfile: {model: "your-model"}`. Labels are declarations, never verified AI identity or permissions. Repeat the label on each batch; missing metadata stays unknown. No pricing is collected or calculated.
|
|
200
|
+
|
|
201
|
+
Savings use the existing output-compaction ledger: original/sent bytes are measured, and estimated saved tokens equal saved bytes divided by four. The monitor totals cover this agent run, grouped by declared model, and reset on restart. They are not provider token counts. Older snapshots show unavailable savings rather than a fabricated zero.
|
|
202
|
+
|
|
203
|
+
The runtime reuses its last 64 shaped terminal results for later completed output reads, so repeated reads match the counted compacted result. The encrypted journal retains the original output. After restart or result-cache eviction, reads fall back to that original output; no historical model attribution or extra savings is invented.
|
|
204
|
+
|
|
205
|
+
Each instance retains its last 64 observed executions, 100 events, 32 sessions and up to 32 model groups in `%LOCALAPPDATA%\LocalCommander\Monitor`. Legacy command classes remain compatible; optional previews show actual executable and simple arguments (24 arguments, 240 characters maximum). Inline scripts, credential flags/paths, headers, message bodies and other payload arguments are redacted. Execution result code, timeout, elapsed time and sanitized working directory provide context without retaining tool output. Child PIDs are runtime notifications; the companion PID is identified separately.
|
|
206
|
+
|
|
207
|
+
`logs` shows recent events, model/command classifications and measured compaction or passthrough sizes. Its initial review lists the five largest remaining outputs and suggests focused file reads/searches, lower command verbosity or less polling when the observed counts justify it. These are advisory review candidates, not proven avoidable tokens, automatic command changes or caching. `logs --follow` reports overwritten-history gaps. Last snapshots remain inspectable after a stop, and a new run replaces that state directory's snapshot. `monitor --json` includes all bounded observations, including finished work omitted from the live screen.
|
|
208
|
+
|
|
209
|
+
An older installed agent produces no monitoring snapshot even if it is running; the CLI reports that monitoring is unavailable. Publishing/installing the updated agent is required before these views can report its connection. The existing `status` command remains available for installation and process state.
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
### Monitor measurements and release history
|
|
213
|
+
|
|
214
|
+
The view shows measured per-agent calls, mean tool-plus-queue duration, stdout bytes, sent response bytes and errors when an identified reporter has those counters. Native measured calls, status/output polls and session records are separate figures; sessions are not execution capacity. Current savings totals exclude stale native snapshots. Missing measurements remain unavailable.
|
|
215
|
+
|
|
216
|
+
Release changes are listed in `CHANGELOG.md`, which ships with this package (npm **Code** tab).
|
package/bin/localcommander.mjs
CHANGED
|
@@ -213,7 +213,8 @@ async function identityStatus(runtimeDir) {
|
|
|
213
213
|
if (result.status !== 0) fail(result.stderr.trim() || "IDENTITY_STATUS_FAILED");
|
|
214
214
|
try {
|
|
215
215
|
const parsed = JSON.parse(result.stdout.trim());
|
|
216
|
-
return { paired: parsed.paired === true, accountEmail: typeof parsed.accountEmail === "string" ? parsed.accountEmail : null, deviceId: typeof parsed.deviceId === "string" ? parsed.deviceId : null
|
|
216
|
+
return { paired: parsed.paired === true, accountEmail: typeof parsed.accountEmail === "string" ? parsed.accountEmail : null, deviceId: typeof parsed.deviceId === "string" ? parsed.deviceId : null,
|
|
217
|
+
fullLogs: parsed.fullLogs ?? { enabled: null, confirmedAt: null, manageUrl: DEFAULT_ORIGIN } };
|
|
217
218
|
} catch { fail("IDENTITY_STATUS_INVALID"); }
|
|
218
219
|
}
|
|
219
220
|
async function pair(runtimeDir) {
|
|
@@ -526,6 +527,7 @@ async function statusObject() {
|
|
|
526
527
|
paired: identity.paired,
|
|
527
528
|
accountEmail: identity.accountEmail,
|
|
528
529
|
deviceId: identity.deviceId,
|
|
530
|
+
fullLogs: identity.fullLogs ?? { enabled: null, confirmedAt: null, manageUrl: DEFAULT_ORIGIN },
|
|
529
531
|
stateDirectory: stateDirectory()
|
|
530
532
|
};
|
|
531
533
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
export const AGENT_NAMES: readonly string[];
|
|
2
|
-
export function agentName(id: string): string;
|
|
3
|
-
export interface MonitorContext { project: string | null; directory: string | null; taskId: string | null; pr: number | null; inferred: boolean }
|
|
4
|
-
export function contextSummary(meta?: Record<string, unknown>): MonitorContext;
|
|
5
|
-
export function commandSummary(tool: string, meta?: Record<string, unknown>): string;
|
|
6
|
-
|
|
7
|
-
export function commandPreview(tool: string, meta?: Record<string, unknown>): string;
|
|
1
|
+
export const AGENT_NAMES: readonly string[];
|
|
2
|
+
export function agentName(id: string): string;
|
|
3
|
+
export interface MonitorContext { project: string | null; directory: string | null; taskId: string | null; pr: number | null; inferred: boolean }
|
|
4
|
+
export function contextSummary(meta?: Record<string, unknown>): MonitorContext;
|
|
5
|
+
export function commandSummary(tool: string, meta?: Record<string, unknown>): string;
|
|
6
|
+
|
|
7
|
+
export function commandPreview(tool: string, meta?: Record<string, unknown>): string;
|
|
@@ -1,20 +1,20 @@
|
|
|
1
|
-
export interface LifetimeSavings {
|
|
2
|
-
scope: "all_time";
|
|
3
|
-
coverage: "recorded_native_results";
|
|
4
|
-
since: string | null;
|
|
5
|
-
asOf: string | null;
|
|
6
|
-
calls: number;
|
|
7
|
-
originalBytes: number;
|
|
8
|
-
sentBytes: number;
|
|
9
|
-
savedBytes: number;
|
|
10
|
-
}
|
|
11
|
-
export function lifetimeSavingsView(raw: unknown): LifetimeSavings | null;
|
|
12
|
-
export function summarizeLifetimeSavings(result: {
|
|
13
|
-
instances?: Array<{ lifetimeSavings?: unknown; savingsSourceId?: string }>;
|
|
14
|
-
unavailable?: number;
|
|
15
|
-
}): { available: boolean; partial: boolean; unavailable: number; sources?: number;
|
|
16
|
-
calls?: number; originalBytes?: number; sentBytes?: number; savedBytes?: number;
|
|
17
|
-
since?: string | null; asOf?: string | null; estimatedSavedTokens?: number };
|
|
18
|
-
export function formatLifetimeSavings(result: Parameters<typeof summarizeLifetimeSavings>[0] & {
|
|
19
|
-
mcp?: { instances: Array<{ instanceId: string; metrics?: Array<{ savedBytes: number }> }>; unavailable?: number };
|
|
20
|
-
}): string[];
|
|
1
|
+
export interface LifetimeSavings {
|
|
2
|
+
scope: "all_time";
|
|
3
|
+
coverage: "recorded_native_results";
|
|
4
|
+
since: string | null;
|
|
5
|
+
asOf: string | null;
|
|
6
|
+
calls: number;
|
|
7
|
+
originalBytes: number;
|
|
8
|
+
sentBytes: number;
|
|
9
|
+
savedBytes: number;
|
|
10
|
+
}
|
|
11
|
+
export function lifetimeSavingsView(raw: unknown): LifetimeSavings | null;
|
|
12
|
+
export function summarizeLifetimeSavings(result: {
|
|
13
|
+
instances?: Array<{ lifetimeSavings?: unknown; savingsSourceId?: string }>;
|
|
14
|
+
unavailable?: number;
|
|
15
|
+
}): { available: boolean; partial: boolean; unavailable: number; sources?: number;
|
|
16
|
+
calls?: number; originalBytes?: number; sentBytes?: number; savedBytes?: number;
|
|
17
|
+
since?: string | null; asOf?: string | null; estimatedSavedTokens?: number };
|
|
18
|
+
export function formatLifetimeSavings(result: Parameters<typeof summarizeLifetimeSavings>[0] & {
|
|
19
|
+
mcp?: { instances: Array<{ instanceId: string; metrics?: Array<{ savedBytes: number }> }>; unavailable?: number };
|
|
20
|
+
}): string[];
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "local-commander-agent",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.51",
|
|
4
4
|
"description": "Computer companion for Local Commander: connect AI clients to local files, approved commands and localhost. Requires https://localcmd.app.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -16,9 +16,9 @@
|
|
|
16
16
|
"arm64"
|
|
17
17
|
],
|
|
18
18
|
"optionalDependencies": {
|
|
19
|
-
"local-commander-agent-darwin-arm64": "0.3.
|
|
20
|
-
"local-commander-agent-linux-arm64": "0.3.
|
|
21
|
-
"local-commander-agent-linux-x64": "0.3.
|
|
19
|
+
"local-commander-agent-darwin-arm64": "0.3.51",
|
|
20
|
+
"local-commander-agent-linux-arm64": "0.3.51",
|
|
21
|
+
"local-commander-agent-linux-x64": "0.3.51"
|
|
22
22
|
},
|
|
23
23
|
"engines": {
|
|
24
24
|
"node": ">=20.0.0"
|
package/runtime/JobHost.exe
CHANGED
|
Binary file
|
|
Binary file
|
package/runtime/OwnerBridge.exe
CHANGED
|
Binary file
|