# AgentGem documentation AgentGem is a local web UI that reads what you've already built with your coding agent — your **agent setup** (skills, MCP servers, `CLAUDE.md`) and your **session transcripts** — redacts secrets at capture, and distills it into a **secret-safe, composable Gem**. [Analyze](analyze.md) turns the procedures you repeat across sessions into draft skills; the builder packages it all into a portable archive (manifest + lock) you can install locally, merge with others, materialize for many agent targets, and publish to the AgentGem marketplace. It's built on **[AgentBack](https://agentback.dev)**, the ninemind AI-native API/MCP framework: every operation is defined once as a Zod contract and exposed as a REST endpoint, an MCP tool, and an OpenAPI 3.1 document — so the web page and your local agent call exactly the same thing. ## Start here - **[Getting started](getting-started.md)** — install, run the local server, and build your first Gem. - **[Desktop app](desktop.md)** — the native macOS/Windows/Linux build, in addition to the `npx` CLI. - **[Analyze](analyze.md)** — scan your agent's session history for workflow-aware Gem recommendations, and **distill new draft skills** from the procedures you repeat by hand. - **[Concepts](concepts.md)** — what a Gem is, the archive format, the redaction trust boundary, and the AgentBack one-contract model. - **[Editions](editions.md)** — AgentGem OSS vs. Enterprise, and the community marketplace both share. ## Working with your sessions The console is more than a Gem builder — it reads, searches, and grades your session history, and turns it into things you can play and share. - **[Recall](recall.md)** — search across every past session by what happened inside it, then chat with or extract across the ones that matter. Ranking is **proven-use aware** (artifacts with good outcomes are boosted). Its intelligence is also the **`agentgem-goldmine`** MCP server, so any coding agent can query your history. - **[Memory sync](recall.md)** — the **Memory panel** bridges recall to external AI memory providers (**mem0**, **supermemory**): pull their memories in, and push scrubbed, consent-gated candidates out through a review outbox. - **[Chat](chat.md)** — drive a local coding agent (Claude, Codex) from inside the console, grounded in your transcripts, and distill the conversation into a Gem. - **[Context hygiene](context-hygiene.md)** — LLM-free detection of context bloat: a per-session score, a "cut here at turn N" boundary, a session timeline, a leaderboard, and live OS nudges from the `agentgem warm` daemon. - **[Play](play.md)** — AI-generated mini-games, built by chatting, sealed to run anywhere, and versioned as first-class `game` Gems. ## Architecture & internals - **[Architecture](architecture.md)** — the system map: clients → contract surface → Gem core → distribution, with diagrams. - **[The build pipeline](pipeline.md)** — introspect → redact → buildGem → archive. - **[Archive format](archive-format.md)** — the manifest + lock spec, hashing, and serialization. - **[Redaction](redaction.md)** — the trust boundary and its rules. - **[Input containment](input-containment.md)** — how outward-facing POST routes confine filesystem/network inputs (workspace-name, run-dir, and SSRF guards). - **[API reference](api-reference.md)** — every REST endpoint and MCP tool. ## Distribution - **[Targets](targets.md)** — the materialize targets (Eve, Flue, OpenAI Sandbox, Bedrock AgentCore, and the editor formats) and how a Gem renders to each. - **[A2A](a2a.md)** — export a Gem as an A2A Agent Card or a runnable agent-to-agent server so other agents can discover and call it. - **The community marketplace at [app.agentgem.ai](https://app.agentgem.ai)** — a free hosted service, shared by both [editions](editions.md), where published Gems live: publish composable Gems (Public / Unlisted / Private, versioned), browse, star, review, install, and play installable/offline mini-apps. **Groups and review-gated releases are [Enterprise](editions.md).** Early testbed — hosted data may be reset. - **[Sharing & identity](sharing.md)** — install a published Gem with one command (`agentgem get`), pass one directly over an encrypted one-time hand-off (`agentgem send` / `receive`), and verify a Gem runs across agents (`agentgem verify`). Accounts on the community marketplace use **better-auth** (GitHub, Google, X, or a passkey) with a **`/@handle`** profile hub; the CLI `agentgem bind` ties this machine's signing key to a GitHub account for anti-sybil producer identity. - **[Testbed & run](testbed-and-run.md)** — install a Gem into a local testbed, and run a materialized target locally. ## Contributing - **[Development](development.md)** — build, test, the decorator/compiled-`dist` setup, and code conventions. ## Diagrams Architecture diagrams live in [`diagrams/`](diagrams/) as `.svg` (embedded in these docs), `.png` (raster fallback), and `.html` (interactive, with Copy / PNG / PDF export): - [System architecture](diagrams/system-architecture.svg) - [Gem build pipeline](diagrams/gem-pipeline.svg) - [Distribution](diagrams/distribution.svg) --- # Getting started AgentGem runs as a small local server. A browser can't read your agent's config directory (it's sandboxed), so AgentGem serves the introspection and Gem-building operations from your machine — over both HTTP and MCP — while keeping secrets on-device. ## Prerequisites - **Node.js ≥ 24.** - A supported coding agent — **Claude** (`~/.claude`), **Codex**, or **Hermes** — with skills, MCP servers, and instructions. ## Run it From the directory of the agent project you want to package, run it without installing: ```bash npx @ninemind/agentgem # npm pnpm dlx @ninemind/agentgem # pnpm ``` Or install the `agentgem` command globally: ```bash npm install -g @ninemind/agentgem # or: pnpm add -g @ninemind/agentgem agentgem # --port to override (default 4317, also honors $PORT) ``` The server starts on `127.0.0.1` and prints its URL. Three surfaces come up from the same contract: | Path | What it is | | ------------ | ------------------------------------------------------------- | | `/` | The Gem Builder web UI | | `/explorer` | Swagger UI for the REST API (from the OpenAPI document) | | `/mcp` | The MCP endpoint, so your local agent can call the same tools | ## Build your first Gem AgentGem is **testbed-first**: you point it at an agent project, then crystallize what's there into a Gem. 1. **Open a testbed.** Open `/` and click **Create / open testbed…**. AgentGem detects the folder you launched from as a Claude/Codex project (it has a `.claude` or `.codex`), and also lists projects discovered from your Claude/Codex session history. Pick one and click **Use this**. 2. **Review what's there.** The testbed's own skills, MCP servers, and instructions appear on the left. To pull in user-level (global) artifacts, click **Import from machine…** and select the ones you want. 3. **Select, and watch it seal.** Tick the artifacts to bundle and name the Gem. The **Gem (live)** panel re-renders the pretty-printed `gem.json` on every change — with every secret already shown as ``. 4. **Take it further.** Download `gem.json` (the neutral source every target and the marketplace consume), **test-drive** the agent locally in the testbed, or publish it. ![The Gem Builder: selected skills and MCP servers on the left, the live gem.json on the right with every secret shown as <redacted>.](screenshot.png) ## Targeting a different config directory The API accepts a directory override for testing or non-default homes: ```bash curl 'http://127.0.0.1:4317/api/inventory?dir=/path/to/.claude' ``` ## Calling it from your agent Because every operation is also an MCP tool, your local agent can call `inventory` and `gem` directly over `/mcp` — no browser required. This is the agent-native path: the same contract the web page uses is available to the agent that's building the Gem. ## From source To hack on AgentGem, clone the repo. It's a [pnpm](https://pnpm.io/) project (`npm` works too), and AgentBack uses legacy decorators, so it builds with `tsc` then runs `dist/`: ```bash pnpm install # or: npm install pnpm dev # or: npm run dev — build + start in one step pnpm test # or: npm test — tsc -b && vitest run ``` Next: read **[Concepts](concepts.md)** to understand what's inside a Gem, jump to **[Targets](targets.md)**, or browse what others have published on the **[public marketplace](https://app.agentgem.ai)** (an early testbed — hosted data may be reset). --- # Desktop app AgentGem ships as a native **desktop app** (macOS, Windows, Linux) in addition to the `npx` CLI. It's the same Gem Builder — the desktop app just hosts the local AgentGem server for you and opens it in its own window, so there's no terminal and no `localhost` URL to manage. Under the hood it's a thin [Electron](https://www.electronjs.org/) host: the app's main process forks a local AgentGem core on a private `127.0.0.1` port and points a window at it. That core runs in **client mode** — it serves the console and every local feature (introspect, build, recall, run) but bundles no auth stack and no database; anything hosted (the shared benchmark) is reached over the network through a same-origin proxy to the hosted marketplace. Every local REST endpoint, the MCP surface, and the web UI work exactly as they do over `npx` — secrets still never leave your machine. ## Download Grab the latest build from the [**Releases**](https://github.com/ninemindai/agentgem/releases) page (look for a `desktop-v*` release): | Platform | File | | --- | --- | | macOS (Apple Silicon / Intel) | `AgentGem--arm64.dmg` · `AgentGem-.dmg` | | Windows | `AgentGem-Setup-.exe` (`AgentGem.Setup..exe` in 0.4.1 and earlier) | | Linux | `AgentGem-.AppImage` | > **macOS builds are signed and notarized** (as of `desktop-v0.4.0`). Gatekeeper > opens the `.dmg` and the app normally — the *"AgentGem is damaged and can't be > opened"* message from the unsigned 0.1.1 builds is gone. **Windows and Linux > builds are still unsigned**, so on the SmartScreen prompt choose > **More info → Run anyway**. > > **Upgrading from 0.1.1:** because 0.1.1 shipped unsigned and this build is > signed, macOS auto-update (Squirrel.Mac) won't apply over an installed 0.1.1. > Download this release once by hand; auto-update works normally from there on. ## What you get - **Native folder picker** — choose your agent project with the OS folder dialog instead of typing a path. - **App menu & shortcuts** — standard menu bar with `Cmd/Ctrl+R` reload and native copy/paste. - **System tray** — closing the window hides the app to the tray and keeps the server running; reopen or quit from the tray icon. - **Auto-update** — signed macOS builds update themselves over GitHub Releases (see the 0.1.1 upgrade caveat under [Download](#download)); Windows and Linux update once those platforms are signed. Everything else — building, publishing, and merging Gems — is identical to the web UI. ## Run from source The desktop app lives in [`desktop/`](https://github.com/ninemindai/agentgem/tree/main/desktop) as a self-contained package: ```bash git clone https://github.com/ninemindai/agentgem.git cd agentgem pnpm -C desktop install pnpm -C desktop dev # builds the core + desktop, launches the app ``` `pnpm -C desktop test` runs the desktop unit tests. See the [`desktop/` README](https://github.com/ninemindai/agentgem/blob/main/desktop/README.md) for the full developer workflow. ## Build an installer ```bash pnpm -C desktop dist # unsigned installers under desktop/release/ ``` This bundles the core into a self-contained file, ships the app's assets and its runtime dependencies, and packages a `.dmg`/`.zip` (macOS), `.exe` (Windows), or `.AppImage` (Linux) with [electron-builder](https://www.electron.build/). To produce signed builds, set the signing environment variables (`CSC_LINK`, `APPLE_ID`, …) documented in the `desktop/` README; absent them the build is unsigned. ## How it works The packaged app can't ship the loose server `dist/` — it's an ES module with its own dependency tree — so the build **bundles the core** into a single self-contained file (with its runtime peers alongside). The bundle is built from the **client entry** (`src/client.ts`), which pulls in no better-auth and no PGlite/`pg`, so it stays lean; the build even fails if any of those symbols leak in. The Electron main process **forks** that core as an out-of-process child (not an in-process `import()` — a blocking core once froze the window and stalled every request), waits for it to report the port it bound, then points the window at the local URL. The window loads the same console you get over `npx`; hosted data (the benchmark) is proxied to the hosted marketplace. So the desktop app is never a fork of the web UI — it's the same core, run locally in client mode. ## Troubleshooting - **Windows SmartScreen warning** — expected; the Windows build is still unsigned. Choose **More info → Run anyway**. (macOS builds are signed and notarized, so Gatekeeper no longer warns.) - **Window is blank or the app won't start** — the app shows the underlying error in a dialog. Rebuild from source (`pnpm -C desktop dev`) to see the full logs. - **A second launch focuses the existing window** — that's intentional; AgentGem is single-instance so you never run two servers at once. --- # Analyze: workflow-aware Gem recommendation Picking which skills, MCP servers, and hooks belong in a Gem is hard when a project has dozens installed and you only really use a handful. **Analyze** does it for you: it reads your agent's **session history** for a project, sees which artifacts you actually invoked, and recommends ready-to-build Gems grouped by the workflows you keep repeating. Instead of a flat checklist of everything you have, you get a short list of candidate Gems — each a coherent recurring flow ("code review", "web scraping", "diagram generation") — and one click pre-selects exactly the artifacts it contains. Analyze also does something the inventory alone can't: it **distills brand-new skills** from the work you did *by hand*. A lot of your expertise never becomes an installed artifact — it lives in the raw `Bash → Edit → test → commit` procedure you repeat across sessions. Analyze recovers those recurring procedures and proposes them as **draft skills** you can review and fold straight into the Gem. See [Distilled skills](#distilled-skills) below. ## Run an analysis Open the testbed dialog (**Create / open testbed…** in the header). Every recent and discovered project shows an **Analyze** button. Click it and AgentGem streams its progress live: > Scanning session history… → Scanned 12 transcripts, 30 sessions. Asking Claude… → > Clustering Gems from your usage… → Validating against your inventory… When it finishes you get one or more **candidate Gems**, each with a name, a short rationale, and the artifacts it includes (with the reason each was chosen — e.g. "5 uses across 3 sessions"). Press **"Switch & apply this Gem ▸"** to adopt that project as your testbed and pre-check exactly that Gem's artifacts — then refine the selection by hand if you like and build as usual. Below the candidates, any **distilled skill drafts** appear in their own section — new skills synthesized from your recurring hand-work, each with an **Add to build** and a **write SKILL.md only** action. See [Distilled skills](#distilled-skills). ## What it reads Analyze is grounded in a deterministic **transcript scan** before any AI is involved: - It finds the Claude Code transcripts whose working directory matches the project (under `~/.claude/projects/`), matched by the recorded cwd, not the folder name. - It counts **tool calls** to detect what fired: `Skill(...)` invocations, `mcp__*` tool calls (MCP servers), hook markers, and the project's instructions (`CLAUDE.md`). Each artifact gets an invocation count, how many distinct sessions it appeared in, and recency. - It records which artifacts **co-occur** in the same session, which is how a single project gets split into multiple workflow candidates rather than one big bundle. - For distillation, it also keeps each session's **builtin tool procedure** in order, passed through a **field-aware scrubber** ([`packages/insight/src/scrub.ts`](redaction.md)) that keeps only a structural slice per tool (a command's verb, a file path) and **drops everything else** — file contents, pasted prompts, secrets — before the procedure is ever stored or sent to the agent. Only artifacts that exist in your real inventory are ever *named* in a recommendation — the scan is the source of truth, so it can't invent a skill you don't have. (Distilled skills are the deliberate exception: they're brand-new drafts, gated behind review, not recommendations of installed artifacts.) Artifacts that show up in transcripts but aren't installed are surfaced separately as **gaps** ("used but not in inventory"). ## How the recommendation is made The scan summary is handed to **Claude** (run locally over the [Agent Client Protocol](https://agentclientprotocol.com/)) in read-only **plan mode**, in a neutral working directory so it never pollutes the project's own session history. Claude clusters the usage into 1–4 candidate Gems and explains each. Its output is then **validated against your inventory** — any name it didn't get exactly right is dropped. If Claude is unavailable, times out, or returns nothing usable, Analyze **degrades gracefully** to a deterministic recommendation built straight from usage frequency (marked *agent unavailable*). It never throws and never fails silently — you always get a recommendation. Candidates are labelled by confidence: **high** when Claude proposed the grouping, **medium** for the deterministic fallback. ## Process quality Alongside workflow detection, Analyze also tracks **process quality** — whether the agent made steady progress toward the goal or got caught in unproductive loops, unverified edits, and regress-and-retry patterns. The insight is from **AgentLens** (arXiv:2605.12925), which found that 10.7% of passing SWE-agent trajectories were "Lucky Passes" — correct outcome but poor process — a signal that outcome success alone doesn't capture agent competence. Analyze runs two deterministic detectors on each session's edit and verification history: - **`regression-cycle`** (severity: warn) — fires when a file is edited, then verified ("work complete"), and then edited again 2+ more times after that. Each recurrence costs 20 points. This flags rework and thrashing over completed work. - **`unverified-tail`** (severity: info) — fires when the session includes at least one verification step but also includes edits *after* the final verification. Those tail edits shipped unchecked. Each instance costs 10 points. (Complements the pre-existing `no-verify-finish` detector, which covers the never-verified case.) **ProcessQuality score**: Each session starts at 100 points. Warn findings deduct 20 each, info findings deduct 10 each, and the score floors at 0. The result is labeled: - **≥80: disciplined** — steady progress, verified work, few re-edits. - **≥50: loose** — mixed quality, some unverified edits or moderate rework. - **<50: chaotic** — frequent unverified tail, high regression-cycle rate, or pervasive blind retry. A report also computes **`atRiskRate`** — the fraction of sessions scoring below 80 ("not disciplined") — as a local proxy for process risk. This mirrors AgentLens's lucky-pass metric but does not claim anything about task success; AgentGem observes process, not pass/fail. The detectors already surface through the existing findings consumers (`insightsCore`, `behaviorFindings`, `rubricReport`); you see them in the **Findings** section of the rubric report today. The `ProcessQuality` score itself is also shown as a **Process quality** card in the session drill-down (Inspect → Session), alongside the context-hygiene card. ## Distilled skills The recommendation above only ever names artifacts you already have. But the actual *how* — the procedure that got the task done — usually isn't an installed skill at all; it's the sequence of builtin tool calls (`Bash`, `Edit`, `Read`, `Write`) that the recommendation throws away. **Distillation** recovers it. Alongside the deterministic scan, Analyze keeps the **ordered, redacted builtin procedure** for each session and finds the runs that **recur across sessions** — not whole sessions (those are never identical) but the shared sub-patterns, e.g. `Edit → git add → vitest → git commit`. A second local Claude agent runs **concurrently** with the recommender and turns each recurring procedure into a draft skill, named and scoped by the **mission** it accomplished (drawn from the session's opening task and outcome) rather than by its tools. Each draft is a complete `SKILL.md` — frontmatter (`name`, `description`, `triggers`, `tools`, `mutating`) plus a body of **Contract → Phases → Output Format** that reproduces the steps the agent followed. Drafts are validated the only way unverified content can be: structurally (kebab name, real triggers, a body), for **uniqueness** (a draft never collides with an installed skill), and by **evidence-grounding** (every tool it claims must actually appear in the captured procedure). A draft that fails is dropped; if nothing recurs, you simply get no drafts. A distilled skill is a **draft, never an install.** In the results you can: - **Add to build ▸** — fold the draft into the Gem you're assembling. It's bundled with its full body and a reviewable `SKILL.md` is written under `~/.agentgem/distilled//`. - **write SKILL.md only** — just save the draft to `~/.agentgem/distilled//` to edit and promote into `.claude/skills/` yourself, on your terms. Nothing is ever written into your `.claude/skills/` automatically — the body is agent-authored prose, so it stays behind a human review gate. Once you promote a draft, the next Analyze sees it as a real installed skill and tracks its usage like any other: the loop closes. ## Caching and re-analyzing Results are cached per project (keyed to your transcript files), so reopening a project shows the previous recommendation instantly — marked **cached**. When your sessions change, the cache invalidates automatically. To force a fresh run, use the **↻ Re-analyze** button. ## Where it fits Analyze is an optional on-ramp to the [testbed flow](testbed-and-run.md): a fast way to answer "what did I actually build here, and what's worth turning into a Gem?" You can analyze a project without adopting it, or apply a recommendation and jump straight into building. Everything after the recommendation — building, publishing, merging — is the normal Gem flow. --- # Concepts ## From project to reusable Gem AgentGem starts where you already work: a **project** you've built up with your agent. Over time that project accrues its own setup — project-specific skills, MCP servers, hooks, and instructions — distinct from your global, user-scoped configuration. The flow turns that lived-in project into something portable: 1. **Discover.** AgentGem surfaces the projects you've worked in with your agent — read from your agent's session history — so you don't have to remember paths. (Today this is backed by a recents list; richer session-history discovery is on the roadmap.) 2. **Compose.** It introspects the project's own artifacts (tagged `source: "project"`) and layers them with your **user-scoped** settings (tagged `source: "user"`), so a project artifact never collides with a same-named global one. Skills, MCP servers, hooks, and instructions are captured across **Claude, Codex, and Hermes**. 3. **Iterate.** You keep working in the project — running tasks and workflows — refining the setup until it does what you want. 4. **Crystallize.** When it's right, you capture it as a **Gem**: a secret-safe, reusable archive (secrets redacted at capture). 5. **Publish / materialize.** Publish the Gem to the marketplace, or compile it to a target. The rest of this page covers what that Gem actually is. ## What a Gem is A **Gem** is a portable, secret-safe snapshot of a slice of your coding-agent config — the skills, MCP servers, hooks, and instructions you chose to bundle. It's the unit AgentGem produces and the neutral source that every target and the marketplace consume. You build it once; everything downstream reads from it. A Gem is intentionally *not* tied to any one runtime. The same Gem can be installed back into a local testbed, merged with other Gems, published to the marketplace, or compiled to a target — without rebuilding from your raw config each time. ## The archive format (manifest + lock) On disk a Gem serializes as an archive with two parts: - a **manifest** — the human-meaningful declaration of what the Gem contains (its name, the selected skills, MCP server shapes, whether `CLAUDE.md` is included), and - a **lock** — the resolved, pinned detail that makes a build reproducible. Keeping the manifest and lock separate is what lets Gems compose: merging two Gems means reconciling manifests and re-resolving a single lock, rather than diffing opaque blobs. ## The redaction trust boundary AgentGem's core safety rule: **secrets are redacted at capture.** The moment config is read, MCP secrets are stripped — both by value and by key name (anything that looks like a key, token, or password). Redaction happens *before* anything crosses a boundary, so every REST response, every MCP tool result, the live preview in the UI, and the built Gem all carry only redacted shapes — never raw secret values. Serving this over HTTP and MCP doesn't weaken the boundary: it's the same redaction the original CLI enforced. Secrets stay on your machine; what leaves is a config *shape* with `` in place of every sensitive value. ## The AgentBack one-contract model AgentGem is built on **[AgentBack](https://agentback.dev)**, ninemind's AI-native API/MCP framework. Each operation — `inventory`, `gem` — is defined once as a Zod contract. From that single definition AgentBack derives: - a **REST endpoint** (what the web page calls), - an **MCP tool** (what your local agent calls), - an **OpenAPI 3.1** document plus a Swagger `/explorer`, a typed client, and runtime validation with machine-actionable error envelopes. The payoff is coherence: there's no second schema to drift out of sync. A tool is not a re-implemented endpoint — it's the same contract surfaced at a different boundary. The web UI is just one client of that contract. ## ATIF trajectory interchange **ATIF** — the Agent Trajectory Interchange Format (Harbor RFC 0001) — is the format AgentGem uses for both importing and exporting trajectories. **Importing** is simple: drop `*.json` files into `~/.agentgem/atif/`, and they appear in **Observe** immediately, visible in the **Watch** tab and **Inspect** drill-down as agent `atif`. **Exporting** works from any imported or recorded session — Claude, Codex, or an imported ATIF trajectory. Use the endpoint `GET /api/inspect/session/atif?id=&agent=` to fetch a scrubbed ATIF v1.7 document marked with `schema_version: "ATIF-v1.7"`. Exports are secret-safe by default (redacted at capture), so you can share them freely without exposing API keys or credentials. See the **[ATIF specification](https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md)**. Continue to **[Targets](targets.md)** to see where a Gem can go. --- # Editions AgentGem comes in two editions that share one archive format and one community marketplace. ## AgentGem OSS **MIT-licensed, local-first, free.** `npx @ninemind/agentgem` (or the native [desktop app](desktop.md)) runs a small server on your machine and opens the console. Everything that reads your agent setup and session history, builds and composes Gems, and shares them runs locally: - **Mine your work** — [Analyze](analyze.md) workflow-aware Gem recommendations and distilled draft skills, [Recall](recall.md) cross-session search + the `agentgem-goldmine` MCP server, [context hygiene](context-hygiene.md) scoring and live nudges, and [Chat](chat.md) grounded in your transcripts. - **Build & compose Gems** — the [manifest + lock archive](archive-format.md), [testbed install/merge](testbed-and-run.md), and [materialize targets](targets.md) (Eve, Flue, OpenAI Sandbox, Bedrock AgentCore, editor formats + A2A) with **Run app** locally from the Materialize panel. - **Play** — [AI-authored mini-apps](play.md), sealed to run anywhere and versioned as `game` Gems. - **The marketplace client** — `agentgem get` to install a published Gem, publish-to-Explore, `agentgem send` / `receive` for an encrypted one-time hand-off, and `agentgem verify`. See [Sharing](sharing.md). The OSS package carries **no accounts, no hosted server, no cloud deploy** — it talks to the community marketplace as a pure client. ## The community marketplace **[app.agentgem.ai](https://app.agentgem.ai) — a free hosted service operated by ninemind, shared by both editions.** It's where published Gems live: - Sign in with **GitHub, Google, X, or a passkey**; each account gets a tabbed **`/@handle`** profile hub. - **Publish** a Gem Public, Unlisted, or Private; cut versions; **star** and **review**. - The **arcade** — AI-authored mini-apps as installable, offline-playable PWAs, searchable by genre and tag. - Every shareable link unfurls with a [branded preview card](sharing.md#branded-link-previews). The hosted marketplace is an **early testbed**: treat it as a preview, and expect accounts, stars, and reviews to be reset occasionally. ## AgentGem Enterprise **For teams that need the platform under their control.** Enterprise is in **early access** — a design-partner program, not a self-serve product yet. It adds: - **Teams & governance** — **groups** (share a private Gem, run peer review) and **review-gated releases** (request review → a member installs to test → an approval publishes); **orgs** with a scorecard, team-usage dashboard, and **benchmark governance** over what's contributed. - **Cloud miniapp builds** — build Play mini-apps on managed cloud agents instead of a local coding agent. - **The GitHub App** — repo-native capture and enterprise onboarding. - **Self-host** — deploy the hosted service into your own AWS account via Terraform, or run it fully air-gapped. - **Support** — a direct line to the team. **Interested? Email [raymond@ninemind.ai](mailto:raymond@ninemind.ai).** ## At a glance | | OSS | Enterprise | | --- | --- | --- | | License | MIT, free | Commercial (early access) | | Runs | Locally (`npx` / desktop) | Hosted — cloud or your own AWS | | Mine, build, compose, materialize, Play | ✓ | ✓ | | Marketplace client (`get` / publish / `send` / `verify`) | ✓ | ✓ | | Community marketplace (accounts, `/@handle`, publish, star, review, arcade) | ✓ (shared service) | ✓ | | Groups & review-gated releases | — | ✓ | | Orgs, scorecards, benchmark governance | — | ✓ | | Cloud miniapp builds | — | ✓ | | GitHub App | — | ✓ | | Self-host / air-gap | — | ✓ | | Support | Community | Direct | Email **[raymond@ninemind.ai](mailto:raymond@ninemind.ai)** to join the Enterprise early-access program. --- # Recall: search across every past session Your best agent work is scattered across hundreds of past sessions — the time you got a tricky migration right, the prompt that finally produced the diagram you wanted, the debugging path that worked. **Recall** makes all of it searchable. Open it at **`#/recall`** in the console, type what you remember, and it finds the moments across your whole session history — instantly, and locally. Recall never leaves your machine. The index is built over **scrubbed** transcript turns (the same field-aware scrubber the rest of AgentGem uses — see [Redaction](redaction.md)), so file contents, pasted prompts, and secrets are dropped before anything is indexed. ![Recall — a search box over every past session, with project / agent / since filters and a selection bar with "Chat with these" and "Extract across these" exits.](screenshots/recall.png) ## Search Type a query and results appear as you type (a 250 ms debounce; an empty box does nothing and makes no request). Under the hood it's a **BM25 full-text search** over your transcript turns, backed by SQLite FTS5 through Node's built-in `node:sqlite` — no external database, no server round-trip to anyone else. The index lives at `~/.agentgem/.agentgem/recall-index.db` and builds in the background; a "indexing *N* of *M*" hint shows while it catches up. Ranking is **proven-use aware**. On top of the text score, sessions that used an artifact which went on to produce a *good outcome* get a boost: the insights judge pass records per-session outcomes into a separate `artifact-outcomes.db`, and a Wilson-shrunk outcome score (shrunk so one lucky session can't outrank a track record) nudges the proven work up the list. It's additive — a query still matches on text first; proven use only breaks ties toward what actually worked. Three filters narrow the field: - **Project** — scope to one repo. - **Agent** — Claude, Codex, … - **Since** — Any time · Last 24 hours · Last 7 / 30 / 90 days. ## Moments Each result is a **moment**: the single best-matching turn in a session, rolled up from the underlying turn hits. A moment card shows the **project**, the **git branch**, the **agent**, how long ago it was, the matched snippet with your terms highlighted, and a **"*N* matching turns"** count so you can tell a one-off mention from a session that's really about the thing you searched for. From a moment you can: - **Open turn ↗** — jump straight to that turn in the full transcript (`#/sessions//?turn=`), where the [session timeline](context-hygiene.md#the-session-timeline) and the raw messages live. - **Select it** — click the card to add it to a working set, then take one of two **exits** over everything you've selected. ## Two exits: chat, or extract Selecting a few moments turns Recall from a search box into a way to *ask across* those sessions: - **💬 Chat with these** — a running conversation grounded in the selected sessions. Each message you send starts a fresh fan-out across the same sessions and keeps the prior turns as history, so you can drill in ("which of these used a worktree?" → "show me the exact command"). - **⇩ Extract across these** — one question, one pass, one report you can export as **Markdown, JSON, HTML, or CSV**. Good for "pull every deploy command I ran this month" or "summarize how I set up auth in each of these." Both exits run the same **funnel**: a capped `ask_session` fan-out that reads each selected session for a per-session answer, then a cross-session synthesis pass. The read runs over a local, ephemeral Claude subprocess in **read-only plan mode** — it never edits your files — and degrades to a deterministic join if the agent is unavailable, so an exit always returns something. ## The `agentgem-goldmine` MCP server The same session intelligence that powers Recall is exposed as a standalone **MCP server** so *any* coding agent can query your history, not just the console. It ships as a separate executable, **`agentgem-goldmine`**, installed on your `PATH` alongside `agentgem`. Point your agent's MCP config at it (it speaks MCP over stdio) and the tools appear as `mcp__agentgem-goldmine__`: | Tool | What it answers | | --- | --- | | `search_sessions` | Find past sessions by project, model, or branch (metadata only). | | `search_session_content` | Rank moments across sessions by transcript *content* — the Recall index, over MCP. | | `summarize_session` | An aggregate view of one session: process-quality score, stage mix, detector findings, tool/edit/verify counts — no raw content. | | `ask_session` | Ask a question about one session; a separate agent reads the raw transcript and returns only the answer. | | `get_artifact_detail` | Detail about one installed artifact (`skill`, `mcp_server`, `hook`, or `instructions`). | | `get_behavior_findings` | Recurring problematic patterns in recent sessions (retry storms, thrash loops, unverified finishes) with per-pattern advice. | The console's [Chat](chat.md) tab wires this same server into its sessions automatically, so the agent you chat with can already see your history. ## Where it fits Recall is the read side of your session goldmine: find the moment, then hand it off. Once you've found what worked, **[Chat](chat.md)** about it or **[Analyze](analyze.md)** the project to turn the recurring procedure into a draft skill and fold it into a Gem. --- # Chat: a coding agent inside the console The **Chat** tab (**`#/chat`**) drives a local coding agent — **Claude Code** or **Codex** — from inside AgentGem, and hands it your session history as tools. Start a conversation, explore, then **distill it into a Gem** without leaving the app. ![The Chat tab — an agent dropdown (Claude Code), a "Start in" launcher toggling between Neutral and a project, and a message box.](screenshots/chat.png) ## Pick an agent A single dropdown lists the agents AgentGem can run, from the roster at `GET /api/agents`. If the adapter for one isn't installed yet, you can install it inline: a consent prompt explains it downloads the adapter's npm package (~260 MB) and runs it locally, then the agent becomes available. Agents run over the [Agent Client Protocol](https://agentclientprotocol.com/) (ACP), the same local transport [Analyze](analyze.md) uses. ## Start in a project (or stay neutral) A **Start in** launcher (the same Global/Project picker used across the console) chooses *where* the agent runs: - **Neutral** (the default) — the agent runs in a scratch directory (`~/.agentgem/.agentgem/chat`), with no project checked out. Good for a general conversation about your sessions. - **A project** — point the session at one of your repos so the agent can read that project's files while you talk. The chosen project is **validated server-side against an allow-list** of your discovered and recent projects before the agent connects — a raw path from the browser is never trusted as a working directory. The launcher locks once a chat starts, so a conversation can't be re-homed mid-flight. Chat runs the agent **read-only**: it can read your files and query your history, but it doesn't edit them. (Editing is the job of [Play → Studio](play.md), where the agent is granted write access jailed to a single miniapp directory.) ## Grounded in your history Every chat session is wired to the **`agentgem-goldmine`** MCP server (see [Recall](recall.md#the-agentgem-goldmine-mcp-server)) and seeded with a briefing, so the agent can already answer "what did I do last time I set up auth?" by searching and reading your past transcripts — not just the current context. Assistant replies stream in, and each tool call the agent makes shows as a chip so you can see it searching your sessions. ## Type while it's working You don't have to wait for the agent to finish. Type and send while a turn is streaming and your messages **queue** — they coalesce and flush as the next turn the moment the current one ends. To stop the current turn instead, **Interrupt** (beside *Attach files* in the composer) cancels it at the ACP `session/cancel` seam; the stream reports the turn's stop reason, and anything you'd queued is preserved so you can resume cleanly. The same queue + Interrupt work in Studio. ## Draft a Gem from the conversation Once a chat exists, a **Draft a Gem ◆** button turns the conversation into a candidate Gem — the natural bridge from "I just figured this out by talking it through" to "package it so I can reuse and share it." From there it's the normal [testbed flow](testbed-and-run.md): refine the selection and build. ## On the desktop app The Claude Code and Codex ACP adapters are **bundled into the [desktop app](desktop.md)**, so Chat works there with no separate `npm install` and no global adapter on your `PATH`. --- # Context hygiene Long agent sessions rot. The context window fills with re-read files, half-finished tangents, and tasks that bleed into each other, and the agent gets slower and less sharp the fuller it gets. **AgentGem detects that bloat** — cheaply, with no LLM in the loop — scores each session, tells you where the clean break is, and can nudge you in real time before a live session goes off the rails. The whole thing is **deterministic**: pure scans over the session's tool/turn spine, no fs access and no model calls. The same report is reproducible every time. ![A session drill-down: an SVG context-bloat timeline with skill/subagent markers and a "bounded" verdict, a "biggest context jumps" rail, a process-quality bar, and a Map/Transcript toggle over the session's steps.](screenshots/session-timeline.png) ## What it detects Five context-hygiene detectors run over a session's turns: | Detector | Fires when… | | --- | --- | | `context-pinned` | the window sits pinned near the model's cap for most of the session | | `cache-churn-late` | context churns hardest when it's fullest (the expensive end) | | `task-sprawl` | one session covers many distinct task clusters | | `task-pingpong` | the session keeps switching back and forth between tasks | | `reread-churn` | files get re-read because they fell out of context | Each fired factor subtracts a fixed weight from a **hygiene score** that starts at 100, and the score buckets into a verdict: - **bounded** (≥ 72) — the window stayed lean. - **mixed** (≥ 48) — some drift. - **bloated** (< 48) — the session was fighting its own context. (These are the *context* detectors. The related **process-quality** detectors — `retry-storm`, `thrash-loop`, `no-verify-finish`, and friends — are covered under [Analyze → Process quality](analyze.md#process-quality).) ## The bloat curve and the cut point Behind the verdict is the **bloat curve**: the size of the context window, turn by turn, drawn against the model's cap. On top of it, a deterministic change-point pass segments the session into task **episodes** and picks the single **"cut here at turn *N*"** — the episode boundary with the largest jump in context across it. That's the point where, if you'd started a fresh session, each half would have stayed lean. It's a concrete, reproducible answer to "where should I have cleared context?" ## The session timeline Open any session from **History** (`#/sessions`) and drill into it (`#/sessions//`). For Claude sessions the drill-down renders an **SVG context timeline**: - the bloat curve, with amber/red bands at 50% and 80% of the peak; - shaded **task-episode** segments from the change-point pass; - **skill and subagent markers** along the top, so you can see which loads pushed context up; - the dashed **"suggested cut at turn *N*"** line; - a side rail with the verdict, the hygiene factors that fired, the **biggest context jumps** (each attributed to a loaded skill, a folded-back subagent, an injection, or model output), and the **task areas** — where to cut. Alongside it, a **Map ⇄ Transcript** toggle switches the body between a phase-by-phase **Map** of the session's tool and skill calls and the verbatim **Transcript**. ## The leaderboard Run the built-in **hygiene** (or **context-hygiene**) rubric from the **Rubrics** panel (`#/rubrics`) and each session is ranked **worst-first** — most bloated at the top — with its verdict, score, and the top factor that dragged it down. Each row links straight to that session's timeline. It's the fast way to find which of your recent sessions were the messiest. ## Live nudges: the `warm` daemon `agentgem warm` is a background **precompute daemon** that keeps AgentGem's caches warm as your `.claude` files change — insight, scorecard, usage, and Recall caches — so the console is instant instead of recomputing on every visit. It also raises the context-hygiene alarm while you work: ```bash agentgem warm --watch # run the daemon; re-warm caches as sessions change agentgem warm --watch --nudge # also raise an OS notification when a live session gets heavy ``` With `--nudge`, each time a watched live session's verdict **climbs to a heavier level**, AgentGem fires a native OS notification (macOS `osascript`, Linux `notify-send`) titled **"AgentGem — context is heavy"** with the specific advice for what's bloating it. It only fires on a *worsening* — no nagging while a session sits at the same level. To keep the daemon running across logins, install it as a service: ```bash agentgem warm --install-service # write a launchd (macOS) or systemd --user (Linux) unit agentgem warm --uninstall-service # remove it ``` `--install-service` prints the one command to enable the unit (`launchctl load …` / `systemctl --user enable --now agentgem-warm.service`). It's macOS and Linux only. --- # Play: AI-generated mini-games as Gems **Play** (**`#/play`**) turns your work into small, self-contained HTML mini-games — built by chatting with a coding agent — and treats each one as a first-class Gem you can version, share, and publish. A game about replaying your best session, a skill-runner, a bit of project fun: each is a single sealed HTML file *and* an installable `game` Gem at the same time. Play has three views, all under the one `#/play` route: ![The Arcade — a grid of AI-generated mini-games, each a live click-through thumbnail with a genre tag and an "offline" or live-capability pill.](screenshots/arcade.png) ## Arcade — browse and play The **Arcade** is a grid of your mini-games. Each card renders a live, click-through thumbnail of the actual game (lazily loaded), with a **🟢 offline** pill for games that need nothing from the host and capability pills for ones that ask for live data. Click a card to open it in Studio. ## Composer — start a new miniapp **+ New miniapp** opens the **Composer**, where you pick what to seed the game from: - **Project** — build something around one of your repos. - **Session** — turn a past session into a replay. - **Skill** — a runner for one of your skills. - **HTML** — import an existing single-file game. - **Blank** — start from scratch. Composer doesn't edit the game; it creates it and hands off to Studio. ## Studio — build it by chatting **Studio** is where the game gets made. A coding agent edits the single HTML file in place while you describe what you want, with a **live preview** beside the chat. The agent works within fixed `// ==== AGENTGEM:GAME-LOGIC START/END ====` markers in a scaffold, so the sealed shell around your game stays intact. Studio hosts the three finishing actions — **Save**, **Push to git**, and **Share** — described below. The full authoring contract is the **`agentgem-miniapp`** skill (in [`skills/agentgem-miniapp/`](https://github.com/ninemindai/agentgem/tree/main/skills/agentgem-miniapp)), injected into the Studio agent's first turn so it knows the rules before it writes a line. ### Build in cloud Studio can build games using cloud-hosted managed agents (faster, more capable than local agents). The cloud provider is selectable if more than one is available: > **Gemini provider:** set `GEMINI_API_KEY` to build with Google's Antigravity managed > agent. On a free-tier (non-billed) Google project this costs nothing; note that Google > may use free-tier traffic for training — only your brief and the generated code are > sent, never anything from your AgentGem identity or sessions. A billed key runs the > same code pay-as-you-go; cap per-build spend with `GEMINI_BUILD_MAX_TOKENS`. > All four cloud-build values (and the Claude trio) can also be set from **Settings → > Credentials** — saved keys apply immediately, no restart or shell environment needed. ## The sealed model A mini-game runs in a **sealed iframe with a null origin** — `sandbox="allow-scripts"` with no same-origin access, under a strict Content-Security-Policy that allows inline script and style and `data:` assets but **no network at all**. That's what makes a game safe to run straight from the marketplace: it can't call home, read cookies, or reach your machine. Because the runtime is sealed, a game is **admitted** by a save-time gate (the "seal") that rejects anything that wouldn't work — external `src`/`href`, bare module imports, `fetch`/`WebSocket`/`XMLHttpRequest` and friends — caps the bundle at 1.5 MB, and smoke-loads it to be sure it doesn't throw. If a save fails the seal, Studio shows an actionable banner with a **Fix with agent** button that hands the failure straight back to the agent to correct. Seed data (the session, project, or skill you built from) is baked into the page as an inert `