@harnessforce/claude-code-plugin 0.0.0-stage → 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "harnessforce",
+  "version": "0.2.0",
+  "description": "Harnessforce plugin for Claude Code",
+  "author": {
+    "name": "Lambda Script"
+  },
+  "homepage": "https://github.com/lambda-script/harnessforce-agent",
+  "repository": "https://github.com/lambda-script/harnessforce-agent",
+  "license": "Apache-2.0"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "harnessforce": {
+      "type": "http",
+      "url": "${HARNESSFORCE_URL:-https://harnessforce.dev}/mcp"
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# harnessforce plugin for Claude Code
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `harnessforce` Claude Code plugin links your Claude Code sessions to
+[Harnessforce](https://github.com/lambda-script/harnessforce-agent) Issues. It is distributed through
+the `harnessforce-agent` marketplace in this repository and as the npm package
+`@harnessforce/claude-code-plugin`, which holds the plugin built against the production connection URL
+and does not bundle the CLI (`/harnessforce:setup` installs `@harnessforce/cli` from npm).
+
+## What it contains
+
+| Part | Purpose |
+| --- | --- |
+| `SessionStart` and `UserPromptSubmit` hooks | Register each session and its config snapshot with Harnessforce |
+| `PostToolUse`, `PostToolUseFailure`, `UserPromptExpansion`, `PermissionRequest`, `PostCompact` and `SessionEnd` hooks | Count the configured skills, commands, subagents and MCP servers a session uses, and send the session usage summary |
+| MCP server `harnessforce` (`<connection URL>/mcp`, HTTP) | Tools to start a run, read an Issue, and complete a run |
+| Skill `using-harnessforce` | What Harnessforce records and does not collect, which hook sends what, and when to use the other skills. The `SessionStart` hook injects its body into the context of every session (the build embeds the same text into the hook and the CLI) |
+| Skill `record-run` | Tells the agent when to start and complete a run |
+| Command `/harnessforce:setup` | Checks Node.js, installs the `harnessforce` CLI, asks whether to send content, runs `harnessforce init` (`--send-content` when chosen) and `harnessforce import`, and confirms the first event after a restart |
+| Command `/harnessforce:tune` | Tells you that the agent reads parts of your transcripts through your model provider, runs `harnessforce tune --json`, shows the analysis and the before and after of earlier applied proposals, and makes proposals for the targets with enough data |
+| Command `/harnessforce:status` | Runs `harnessforce top --once --json` and summarizes the sessions on this machine. Read-only |
+| Command `/harnessforce:import` | Runs `harnessforce import` and shows the imported count and why sessions were skipped |
+| Command `/harnessforce:run <issue>` | Shows how to start an agent on an Issue with `harnessforce run --issue <issue> -- <agent>` in a terminal, and how `HARNESSFORCE_ISSUE` ties a session to an Issue. Runs nothing |
+| Command `/harnessforce:help` | Lists the CLI commands (`harnessforce --help`) and these commands, and says which ones are not wrapped (`init`, the interactive `top`) |
+| Skill `propose-improvements` | How the agent writes a proposal (evidence, diff or pull request draft, expected effect, how to measure), keeps permissions minimal and loops bounded, and records it with `harnessforce tune record` before showing it |
+
+The hooks and the MCP server exist only in the build output, because their scripts and connection URL
+come from the build. The copy of the plugin in this repository has no hooks and no MCP server. See
+[Building the local marketplace](../../docs/runbooks/local-marketplace.md).
+
+## Install
+
+The marketplace installs the plugin from npm, with no version pinned, so you get the latest
+published version:
+
+```text
+/plugin marketplace add lambda-script/harnessforce-agent
+/plugin install harnessforce@harnessforce-agent
+/harnessforce:setup
+```
+
+To connect to a staging or local `apps/web` instead, install the
+[local marketplace build](../../docs/runbooks/local-marketplace.md).
+
+## Requirements
+
+Node.js 18 or later on `PATH`. Without it, Claude Code shows a non-blocking `hook error` and the session
+continues without sending anything.
+
+## Warnings
+
+When a hook cannot send, it shows one line in the session instead of staying silent: Node.js older than 18,
+a failed restart of the hook process, sending not set up (`/harnessforce:setup`), an endpoint that is set
+but not allowed, no ingest key in the keychain (for example after a reboot cleared the kernel keyring), a
+destination that differs from the one `harnessforce init` saved, the Claude Code telemetry settings that
+`harnessforce init` wrote missing from the user settings, a keychain that could not be read, and a session
+registration that failed with anything other than 401. The line appears only at a session start that
+registers (`startup`, `clear`, `fork`), except for the two startup failures, which appear at every session
+start. Nothing is shown while sending works, and nothing is checked again later in the session. When
+`harnessforce` is not on `PATH`, the hook shows nothing: Claude Code reports that `otelHeadersHelper` failed.
+
+## Updates
+
+The hooks send `User-Agent: harnessforce-claude-code-plugin/<version>` and keep the update status the
+server returns in `${CLAUDE_PLUGIN_DATA}/update-status.json`. When a session starts they show one line
+for a newer version (once a day, and not while Claude Code updates the plugin automatically), for the
+date a version stops sending after a security fix, or for an unsupported version. An unsupported version
+sends nothing until you run `claude plugin update harnessforce@harnessforce-agent`; the session keeps
+running. `harnessforce init` turns on automatic updates for the `harnessforce-agent` marketplace.
+
+## Session registration hooks
+
+The `harnessforce` plugin registers each Claude Code session with Harnessforce so that runs can be
+linked to issues. On `SessionStart` (`startup`, `clear`, `fork`) it sends the session ID and the git
+repository, branch and commit of `cwd` to `POST <HARNESSFORCE_ENDPOINT>/v1/sessions`. On the first
+prompt it sends the same registration again with the prompt ID. Prompts, responses and file
+contents are never sent.
+
+- For an organization, set `HARNESSFORCE_ENDPOINT` (the ingest base URL, `https:`) and
+  `HARNESSFORCE_INGEST_KEY` (a Workspace ingest key) in
+  the `env` of the managed settings file (`managed-settings.json` or `managed-settings.d/*.json` in
+  the managed directory). The hook reads the Workspace key and its endpoint only from those files,
+  never from the process environment, because a repository's `.claude/settings.json` can set
+  environment variables. Values distributed through MDM or server-managed settings are not read.
+  Hooks do not receive `OTEL_*` variables, so these are separate.
+- Without a managed Workspace key, the hook sends to `HARNESSFORCE_ENDPOINT` from the environment with
+  the user ingest key that `harnessforce init` stored for
+  `HARNESSFORCE_WORKSPACE_ID`, reading it by running `harnessforce otel-headers` from `PATH` (1 second limit).
+  With a user key and `HARNESSFORCE_ISSUE` (set by `harnessforce run`), the registration claims `source=cli`
+  with that issue identifier. A Workspace key never claims `source=cli`.
+- Requires Node.js 18 or later on `PATH`. The hook always exits 0: outside a git repository, without
+  configuration, on errors, or after 2 seconds it gives up quietly and writes the reason to stderr
+  (Claude Code's debug log). Without Node.js, Claude Code shows a non-blocking `hook error`.
+- If the key is revoked, Claude Code shows once per session:
+  "The organization's ingest key has been revoked. Contact a Workspace administrator" (Workspace key) or
+  "Your ingest key has been revoked. Run `harnessforce init`" (user key)
+
+## Config snapshot
+
+At the same `SessionStart`, the hook also sends a config snapshot to
+`POST <HARNESSFORCE_ENDPOINT>/v1/config-snapshots`, including outside a git repository. The snapshot
+describes the agent configuration as a list of components. Each component has a kind, a scope and
+an identifier, plus a SHA-256 hash:
+
+- CLAUDE.md files and rules, skills, agents, commands and workflows, from the managed directory,
+  `~/.claude` and the repository root.
+- `hooks`, `permissions` and `model` from each settings file.
+- MCP servers from `.mcp.json`, `~/.claude.json` and `managed-mcp.json`.
+- The same kinds of component from enabled marketplace plugins in the plugin cache.
+
+File contents, settings values and MCP server configuration (URLs, headers, environment) are never
+sent, only their hashes. The hashes of hooks and MCP servers leave out the values that can carry
+credentials: `env` and `headers` values, `args`, and the userinfo, query and fragment of URLs, so a
+hash cannot be brute-forced back to a short secret. Nothing is sent when there are no components, and the snapshot is skipped
+when collection takes over 1 second or finds more than 1,000 components. The collector lives in
+`packages/agent-core/src/config`, shared with `harnessforce run` so it can compute the same snapshot ID.
+
+## Session usage summary
+
+The hooks count, per session, the calls and failures of skills (started through the Skill tool),
+commands (typed by you), subagents (started through the Agent tool) and MCP servers, plus permission
+requests and compactions, and send one summary per session to
+`POST <HARNESSFORCE_ENDPOINT>/v1/session-usage`. Claude Code's telemetry hides the names of your own
+skills, commands, subagents and MCP servers, and the setting that reveals them also sends Bash
+commands and file paths, so the hooks count the names themselves.
+
+- Only names that are identifiers in the session's config snapshot are sent; other calls, such as
+  built-in subagents, are added to an `other` count. Each list keeps the 200 most called names. Prompts,
+  command arguments, tool inputs and results, error messages, compaction summaries and file paths are
+  never read into the record or sent. The MCP tool name is reduced to its server.
+- The record lives in `${CLAUDE_PLUGIN_DATA}/usage/`: `<session_id>.jsonl` holds one line per counted
+  call (time, prompt ID, kind, identifier, failure) and `<session_id>.json` holds the Workspace, the
+  session's identifiers and how much of the record was sent. `SessionStart` creates them when it has a
+  destination and a key, and removes files unchanged for 30 days, up to 100 at a time.
+- With a Workspace key from managed settings, `SessionEnd` sends the summary within 1 second of its
+  start, without running `harnessforce otel-headers`, because Claude Code gives all `SessionEnd` hooks 1.5 seconds
+  together. With a user key, or when that send fails, the next `SessionStart` sends up to 20 summaries of
+  other sessions of the same Workspace whose record has not changed for 10 minutes, oldest first.
+- The counting hooks run asynchronously and never delay the agent. Failures are written to stderr as
+  `harnessforce: session usage failed (<reason>)`; a `401` at `SessionStart` shows the revoked-key
+  notice like the registration does.
+
+## License
+
+[Apache-2.0](../../LICENSE)

package/commands/help.md

@@ -0,0 +1,31 @@
+---
+description: List the harnessforce CLI commands and the /harnessforce:* commands, and say which one to use for what
+disable-model-invocation: true
+---
+
+# Harnessforce help
+
+Show the user this guide. To list the CLI commands with a one-line description each, run:
+
+```sh
+harnessforce --help
+```
+
+If the command is not found, tell the user to run `/harnessforce:setup`. `harnessforce <command> --help` shows what a command does, what it sends and does not send, and its exit codes.
+
+## Commands in a session
+
+| Command | What it does |
+| --- | --- |
+| `/harnessforce:setup` | Installs the CLI, connects to Harnessforce with `harnessforce init`, imports past sessions and confirms the first event. |
+| `/harnessforce:status` | Summarizes the sessions on this machine (read-only). |
+| `/harnessforce:import` | Imports past sessions. |
+| `/harnessforce:tune` | Analyzes your past sessions and proposes improvements. |
+| `/harnessforce:run <issue>` | Shows how to start an agent on an Issue. |
+
+## Not wrapped
+
+- `harnessforce init` opens a browser to log in and takes up to 5 minutes, so it is not wrapped as its own command. `/harnessforce:setup` runs it for you.
+- `harnessforce top` without `--once` is an interactive view that needs a terminal. Run it in a terminal.
+- `harnessforce run` starts an agent as a new process. See `/harnessforce:run`.
+- `harnessforce otel-headers` and `harnessforce hook` are run by the agents, not by you.

package/commands/import.md

@@ -0,0 +1,18 @@
+---
+description: Import your past sessions on this machine into Harnessforce and report how many were imported and why others were skipped
+disable-model-invocation: true
+---
+
+# Import past sessions
+
+`harnessforce import` sends a summary of each past session of the repositories connected to your Workspace, inside the import window. It sends no prompt text, responses, tool inputs or results, or code. It is safe to run again, because sessions that were already sent are skipped.
+
+Run it:
+
+```sh
+harnessforce import
+```
+
+- If the command is not found, tell the user to run `/harnessforce:setup` and stop.
+- If it reports that you are not logged in, tell the user to run `/harnessforce:setup` (it runs `harnessforce init`, which needs a browser) and stop.
+- Show the imported count and the breakdown of skipped sessions with the next action, exactly as printed. Do not leave out the reason when nothing was imported.

package/commands/run.md

@@ -0,0 +1,25 @@
+---
+description: Explain how to start an agent on a Harnessforce Issue with harnessforce run, because a session cannot start its own agent
+argument-hint: "<issue-identifier>"
+disable-model-invocation: true
+---
+
+# Run an agent on an Issue
+
+`harnessforce run` starts an agent for an Issue. It has to start that agent as a new process in a terminal, so this command cannot do it from inside a session. It runs nothing. It only shows the steps.
+
+Take the Issue identifier from `$ARGUMENTS` (for example `ABC-123`). If it is empty, ask the user for it.
+
+## Start the agent in a terminal
+
+Tell the user to run this in a terminal, outside this session. Replace `claude` with the agent to start (for example `codex`).
+
+```text
+harnessforce run --issue <identifier> -- claude
+```
+
+Everything after `--` is passed to the agent unchanged. The agent's exit code becomes the exit code of `harnessforce run`. It needs `harnessforce init` to have been done; if not, run `/harnessforce:setup` first.
+
+## Already in a session?
+
+The plugin's hooks tie a session to an Issue when the environment variable `HARNESSFORCE_ISSUE` is set to the identifier before the agent starts. `harnessforce run` sets it for you. This session was started without it unless the user set it, and an environment variable cannot be added to a running session. To work on the Issue, start a new session as above.

package/commands/setup.md

@@ -0,0 +1,65 @@
+---
+description: Harnessforce setup. Walks through checking Node.js, choosing whether to send prompt content, installing the CLI, running harnessforce init, importing past sessions, and confirming the first event after the restart
+disable-model-invocation: true
+---
+
+# Harnessforce setup
+
+Go through the steps below in order, interacting with the user. If a command fails, show its output to the user and stop without moving on to the later steps.
+
+## 1. Check Node.js
+
+First run `node --version`. If the command is not found, or the version is below 18, do not move on to installing the CLI. Show the following text as it is and stop.
+
+> Harnessforce hooks require Node.js 18 or later. Install Node.js, restart Claude Code, then run `/harnessforce:setup` again.
+
+## 2. Check whether this run is after the restart
+
+If `harnessforce --version` succeeds and the environment variable `HARNESSFORCE_WORKSPACE_ID` of this session is not empty, this is a session restarted after `harnessforce init`. Skip steps 3 to 7 and go to step 8.
+
+## 3. Install the CLI
+
+Run the following, then confirm the install with `harnessforce --version`.
+
+```sh
+npm install -g @harnessforce/cli
+```
+
+## 4. Choose whether to send prompt content
+
+Before `harnessforce init`, present the option to send prompt content to the user, not selected by default. The login is not done yet at this point, so neither the Workspace to connect nor its opt-in state is known. Do not change what you show depending on the opt-in.
+
+Present the option together with the following.
+
+- If selected, the body of the prompts the user types to the agent is delivered to this Workspace. Secret patterns, email addresses, and phone numbers are replaced with `[REDACTED:kind]` before storing, and the content is deleted after the content retention period (at most 30 days). Secrets and personal information that do not match a pattern are not masked, and not everything can be detected. Within the Workspace, only the person who sent the stored content can read it; Owners and Admins cannot read it either. That person can delete their own content at any time from My practices.
+- Content is stored only when both this setting on the device and the Workspace opt-in are in place. If the Workspace opt-in is withdrawn, later content is discarded on receipt and existing content data can no longer be read. This setting does not enable sending model responses or tool input and output.
+- If selected, run `harnessforce init --send-content`; if not, run `harnessforce init` (step 5). Write this setting to the `env` of the Claude Code user settings, and do not write it to the `env` of the project (`.claude/settings.json`) or local (`.claude/settings.local.json`) files, because the content variable is ignored in the `env` of those two files.
+- To stop after selecting it, set `OTEL_LOG_USER_PROMPTS` in the `env` of the user settings to `0`. The value that stops it also takes effect in the project and local `env`.
+
+Use the following option text as it is.
+
+> You can send the prompts you type for analysis (off by default; it takes effect only if the workspace has opted in to prompts you typed). If enabled, the prompts you type to the agent are delivered to this workspace and stored. Values that match known patterns for secrets and personal information are replaced with `[REDACTED:kind]`, but not everything can be detected. Content is deleted after the content retention period (at most 30 days), and within the workspace only you can read it. You can delete it at any time from My practices. Enable this?
+>
+> Content is not sent (by default). You can enable it later.
+
+## 5. Connect to Harnessforce
+
+Follow the choice in step 4: run `harnessforce init --send-content` if selected, or `harnessforce init` if not. Tell the user to log in to Harnessforce in the browser and choose one Workspace to connect. If the browser does not open, show the user the URL that `harnessforce init` prints. The command waits up to 5 minutes for the login to complete, so run it with a Bash timeout of 10 minutes.
+
+For a Workspace that has not opted in, `harnessforce init --send-content` does not write the content setting. It prints a message about that and about the Data retention page of the Workspace settings, and exits with code 0. Do not treat this as a failure; show the printed text to the user as it is.
+
+## 6. Import past sessions
+
+Run `harnessforce import` and tell the user, as it is, the imported count it prints, along with the breakdown of sessions that were not imported and the guidance. Do not omit the printed reason and the next action even when the count is 0.
+
+## 7. Ask for a restart
+
+Tell the user the following and stop.
+
+> Harnessforce setup, part 1 of 2, is done. Restart Claude Code, then run `/harnessforce:setup` again in the new session. Part 2 checks that the first event arrived.
+
+## 8. Confirm the first event
+
+At the start of this session, the plugin hook sent the session to Harnessforce. Tell the user to open the Harnessforce Home in the browser (the URL in the environment variable `HARNESSFORCE_URL`) and confirm on the waiting screen for the first Run that it was received. If nothing arrives after 15 minutes, tell the user to follow the checks for each cause shown on the waiting screen. Finish with the following line.
+
+> Harnessforce setup is complete.

package/commands/status.md

@@ -0,0 +1,26 @@
+---
+description: Show the running and recent agent sessions on this machine as a short summary, using a read-only snapshot of harnessforce top
+disable-model-invocation: true
+---
+
+# Session status
+
+This command only reads. It changes no file, setting or Workspace data, and sends nothing to Harnessforce.
+
+## 1. Take a snapshot
+
+Run this once. It prints one snapshot as JSON and exits, so it does not open the interactive view.
+
+```sh
+harnessforce top --once --json
+```
+
+If the command is not found, tell the user to run `/harnessforce:setup` and stop. If it fails, show its output as is and stop.
+
+## 2. Summarize
+
+Summarize the snapshot for the user in a few lines: how many sessions are running, which agent and repository each belongs to, and any recent sessions that ended. Report only values that are in the JSON. Do not guess a value that is missing, and do not turn a missing value into 0.
+
+## 3. Point to the live view
+
+The interactive view needs a terminal, so this command does not start it. Tell the user to run `harnessforce top` in a terminal when they want the live view.

package/commands/tune.md

@@ -0,0 +1,39 @@
+---
+description: Analyze your past sessions and show the analysis results, the before and after of the previous suggestion, and suggested improvements for human interventions, repeatable loops, MCP servers, and usage. Does not modify files
+argument-hint: "[--all] [--no-send]"
+disable-model-invocation: true
+---
+
+# Analyze past sessions and suggest improvements
+
+Go through the steps below in order. This run does not modify the user's files, settings, repository, or managed settings. The only things written are what `harnessforce tune` and `harnessforce tune record` write to `~/.harnessforce/tune/`.
+
+## 1. Say that content goes to the model provider
+
+Before running anything, show the following text as it is.
+
+> To make suggestions, the agent reads part of the session records on this device in this run. What it reads goes to the provider of the model you normally use with this agent, through the same path as a normal session. It does not go to Harnessforce. Harnessforce receives only the analysis result values counted by the public rules.
+
+## 2. Analyze
+
+Run the following. It starts `harnessforce tune --json` and shows the analysis results and, for each target, the result of checking the conditions for making a suggestion. It includes sending and resending unsent results, so set the Bash timeout to 10 minutes.
+
+```sh
+node "${CLAUDE_PLUGIN_ROOT}/skills/propose-improvements/scripts/summarize.mjs" $ARGUMENTS
+```
+
+- The lines on stderr are the messages of `harnessforce tune`. Show all of them as they are, without omitting or rephrasing them.
+- Show the analysis results on stdout (human interventions, repeatable loops, MCP servers, usage) as they are. Do not rephrase "not measured" as 0. Usage values stay on this device and are not sent to Harnessforce.
+- If there is a "Before and after the previous suggestion" section, show it as it is before the new suggestions, and do not omit "Before/after difference (does not show causation)" or "The starting point is the time the application was detected". Do not rephrase "No comparison data" as a difference of 0.
+- If the exit code is anything other than 0 or 3, finish without making suggestions. The same applies when the message says `harnessforce` was not found.
+- If there is a "Not enough data, so no suggestions are made" line, show that line and finish without making suggestions.
+
+## 3. Make suggestions
+
+Show all the "Targets for suggestions" lines. Show the "Not enough data" and "not measured, so no suggestion is made" lines as they are, including what is still needed, and make no suggestion for those targets.
+
+For the targets marked "a suggestion can be made", make suggestions by following the `propose-improvements` skill of this plugin, record them with `harnessforce tune record`, and then show them. Do not show a suggestion whose recording did not end with exit code 0.
+
+## 4. Explain how to apply
+
+Finally, tell the user that applying the suggestions is up to the user. They apply them by editing by hand, running `git apply`, or telling the agent in their own session to apply them. This command does not apply them. A suggestion that was applied is detected in the next run of `/harnessforce:tune`, and only counts are sent to Harnessforce.