> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/operate/developer-agent-activity.md). # Developer Agent Activity What Heeler collects from developer workstations running coding agents, how it is protected, and the three views that report it. A collector installed on a developer machine reports the coding-agent sessions run there, the agent tooling installed on the machine, and the configuration that tooling loads. **Agents** in the navigation reports all three. {% hint style="info" %} **Who this is for:** administrators. Every page and every report here is restricted to **Administrator** and **Administrator (read-only)**. {% endhint %} ## What the collector reads | Source | What it covers | | --------------------------------- | ------------------------------------------------------------------------------------------------------- | | **Agent sessions** | Conversation transcripts from Claude Code, Codex, OpenCode, Cursor, and GitHub Copilot Chat in VS Code. | | **Skills and instruction files** | Skill directories, `AGENTS.md`, `CLAUDE.md` and the equivalent instruction files for each harness. | | **MCP configuration** | The MCP server definitions each harness loads. | | **Hooks** | Hook files and hook configuration for each harness. | | **Editor extensions** | Installed extensions, reported where they relate to AI tooling. | | **Package-manager configuration** | Registry and trust configuration such as `.npmrc`, `.yarnrc` and `pip.conf`. | | **Repository context** | The Git remote, branch, head commit and clean-or-dirty state of the directory a session ran in. | The collector runs for the current user, or across the machine's user accounts, depending on how it was installed. ## What is uploaded Session transcripts are uploaded with their original text. | Uploaded | Detail | | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Transcript events** | The prompt text, the agent's responses, the tool called, and the tool's input and output, in the order they occurred. | | **Session metadata** | Session identifiers, agent version, project path, working directory, start and end times, and token usage. | | **Machine identity** | The machine's Heeler identifier, plus its hostname, local username, platform and architecture. | | **Repository context** | The repository root, remote URL, branch, head commit and dirty state. | | **Tooling inventory** | The skills, MCP servers, and AI-related extensions installed, with paths, versions and content hashes. | | **Configuration files** | The contents of the skill, instruction, hook, configuration and package-manager files listed above. | ### What is removed before upload | Item | Treatment | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Git remote URLs | Any username, password, query string and fragment is stripped. | | MCP server URLs | Credentials, query strings and fragments are stripped. | | MCP server arguments | An argument that looks like a token, secret, password, API key, authorization header or credential is replaced with ``. | | MCP environment variables | Only the variable **names** are inventoried. Values are not. | | Oversized event fields | A transcript field over 1 MB is truncated, and the record keeps the original size and a hash. | | Oversized files | A configuration file over 8 MiB is not uploaded. | | Local session databases | The agent's own databases stay on the machine. Only the normalized session is uploaded. | The collector performs no secret scanning of its own, and its local detections never quote the command or tool output that triggered them. ### Secret detection after upload Heeler scans the uploaded transcript for exposed credentials and records a detection where it finds one. The detection stores a fingerprint hash, not the matched value. Where a finding's evidence could itself contain secret material, the reports show a withheld-evidence notice in its place. ## Credentials Each machine authenticates as itself. {% stepper %} {% step %} ### Issue a deployment token An administrator creates a deployment credential in Heeler. It can carry an expiry. Copy it when it is shown; it is not retrievable afterwards. {% endstep %} {% step %} ### Enroll the machine On first run, the collector generates a key pair on the machine, presents the deployment token once, and receives its own machine credential. The private key never leaves the machine, and the deployment token is not written to disk. {% endstep %} {% step %} ### Every upload is signed Each request is signed with the machine's key and carries its credential. Heeler resolves the tenant from the credential, never from anything the machine reports about itself. {% endstep %} {% endstepper %} ### Revoking | Action | Effect | | ------------------------------------ | ------------------------------------------------------------------ | | Revoke a **machine credential** | That machine stops uploading. Others are unaffected. | | Revoke the **deployment credential** | No new machine can enroll. Machines already enrolled keep working. | A machine credential does not expire on its own. To replace a machine's key, revoke its credential and enroll the machine again. ## Retention of raw evidence Each indexed session carries a retention date. After it passes, the session's raw transcript is no longer readable in Heeler and the drawer reads **Raw transcript expired**. The session's indexed metadata — its counts, tokens, tools, commits and detections — remains. Viewing raw transcripts is enabled separately from the rest of the capability. Where it is not enabled, the **Conversation** tab reads **Raw transcripts disabled** and the rest of the session stays available. ## Sessions **Agents → Sessions** lists indexed agent sessions. Filter by **Agent**, **Machine** and **Repository**, over a **7D**, **30D** or **90D** period. The KPI bar totals **Non-cached Tokens**, **Non-cached Input**, **Cached Input**, **Output Tokens**, **Tool Invocations**, **Sessions** and **Machines** for the filtered set. | Column | What it shows | | --------------------- | ----------------------------------------------------- | | **Session** | The session's title. | | **Agent** | The harness that ran it. | | **Machine** | The machine that reported it. | | **Identity** | The local user on that machine. | | **Repository** | The repository the session worked in. | | **Last activity** | The most recent event in the session. | | **Non-cached tokens** | Tokens the session consumed outside the prompt cache. | | **Sub-agents** | Delegated sessions folded into this one. | | **Tool invocations** | Tool calls made. | | **Detections** | Detections raised against the session. | Open a session for its **Overview**, **Conversation**, **Skills**, **Commits**, **Sub-agents** and **Detections** tabs. The Conversation tab shows the transcript event by event, with a **Show tool details** control for each tool call's input and output. Where a view reaches its result limit, a **Partial results** notice appears; narrow the period for complete totals. ## Workstations **Agents → Workstations** lists the machines that have reported, with what each has installed. | Column | What it shows | | ------------------ | ---------------------------------------------------- | | **Workstation** | The machine's hostname. | | **Users** | The local users seen on it. | | **Platform** | Its operating system. | | **Last collected** | When it last reported. | | **Skills** | Installed skills. | | **MCP servers** | Configured MCP servers. | | **AI extensions** | Installed AI-related editor extensions. | | **Files analyzed** | Configuration and agent files Heeler analyzed. | | **File findings** | Findings across those files. | | **Worst score** | The lowest score among them. A lower score is worse. | | **Shell hooks** | Hook files that run shell commands. | | **Passive** | Whether the collector is running passively. | | **Proxy** | Whether a proxy is in use. | Open a machine for its **Overview**, **Security**, **Changes**, **Skills**, **MCP servers**, **Extensions**, **Hooks**, **Configurations** and **All files** tabs. The **Changes** tab compares the latest snapshot with the previous one and lists what was added, removed and changed, with the hash of each file before and after. ## Security posture **Agents → Security posture** measures the fleet against workstation security signals. The header totals **Workstations**, **Affected machines**, **Observations**, **High / critical**, **Remote MCP** and **Shell hooks**. **Fleet observations** groups the signals by rule, worst first, with the number of workstations each affects. | Column | What it shows | | ------------------ | ----------------------------------------------- | | **Workstation** | The machine. | | **Users** | Its local users. | | **Highest signal** | The most severe observation on it. | | **Observations** | How many signals it raised. | | **Remote MCP** | MCP servers it reaches over the network. | | **Shell hooks** | Hook files that run shell commands. | | **File findings** | Findings in its analyzed files. | | **Changed** | Files that changed since the previous snapshot. | | **Last collected** | When it last reported. | ## Related * [Agent and Instruction Files](/mrecEO40m5D6bt7Pq5pE/catalog/files.md) — the same kinds of file, as found in your repositories. * [Secure AI Coding Agents](/mrecEO40m5D6bt7Pq5pE/solutions-and-use-cases/secure-your-ai-coding-agents.md) — the wider playbook. * [Users and Roles](/mrecEO40m5D6bt7Pq5pE/administer-and-monitor/manage-access/users-and-roles.md) — the roles that can reach these pages. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/operate/developer-agent-activity.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.