Related Pages

Related topics: Core Harness Tools, Serena Proxy & Workflow Skills, Deployment, Drift Detection & Operations

Plugin Overview & System Architecture

Purpose and Scope

The astrojones plugin is a Claude Code plugin that orchestrates repository-aware agent workflows. It packages several cooperating sub-plugins — notably harness, deploy, perception, and mem — under a single marketplace distribution so that an agent can bootstrap a project, monitor its state, deploy it, and recall prior context across sessions.

Distribution is handled through Claude Code's marketplace mechanism. .claude-plugin/marketplace.json describes the marketplace entry, and .claude-plugin/plugin.json provides the plugin manifest (name, version, description, sub-plugin list). At the time of writing, the manifest tracks v3.23.0 as the latest release, with feat(mem): cognee ↔ claude-mem coexistence (P2) shipped via PR #42 as the most recent change. Source: .claude-plugin/plugin.json

High-Level Architecture

The system is composed of three runtime layers wired together by configuration files at the repository root:

1. Plugin layer — marketplace and plugin manifests describe which sub-plugins ship together and at which version.
2. Agent integration layer — .claude/settings.json configures Claude Code's hooks, permissions, and tool wiring that the plugin relies on at runtime.
3. MCP server layer — .mcp.json declares Model Context Protocol servers that the agent calls as tools; run-mcp.sh is the launcher invoked for stdio servers.

Because the harness is stdio-based, delivery currently relies on Claude Code hooks rather than the experimental MCP server-push claude/channel capability, which is known to be unreliable from stdio servers (anthropic/claude-code #45563, #36431). This is the constraint behind issue #36. Source: .mcp.json, run-mcp.sh

A simplified view of the runtime topology:

flowchart LR
  User --> ClaudeCode[Claude Code]
  ClaudeCode -->|hooks| Settings[".claude/settings.json"]
  ClaudeCode -->|tools| MCP[".mcp.json servers"]
  MCP --> Launcher[run-mcp.sh]
  Launcher --> Plugins[harness / deploy / perception / mem]
  Plugins --> RepoState["repo_state snapshot"]

Sub-Plugins and Responsibilities

The plugin manifest groups several cooperating sub-plugins. Each owns a distinct concern:

• harness — bootstraps a repository for agent use. The commands/harness-init.md slash command drives repo_bootstrap, which is already parametrized. The harness ships at v3.9.2 with no version drift against its own manifest. Source: commands/harness-init.md
• deploy — provides deploy-validation tooling. Its surface has drifted relative to the harness's deploy-validation checks, which is the motivation behind issue #37 ("T6 — De-hardcode the harness deploy tool"), currently P2 and release-blocked. Source: .claude-plugin/plugin.json
• perception — runs a background daemon that maintains a repo_state snapshot and feeds a digest into the UserPromptSubmit hook. v1 covers branch/HEAD switches and merge conflicts. Planned extensions include external-edit detection for files the agent is editing (#34), CI-status folding (#33), and eventual consolidation of repo_verify_changed and repo_health into repo_state (#35). Source: .claude/settings.json
• mem — memory subsystem. As of v3.23.0, it supports coexistence between cognee and claude-mem: the agent mirrors memories between the two, removes client-side capture, and gates recall off by default. Source: .claude-plugin/plugin.json

Configuration Surfaces

The repository root holds the configuration files that define how the plugin attaches to Claude Code and which tools it exposes. .claude-plugin/marketplace.json registers the plugin for marketplace distribution, .claude-plugin/plugin.json carries the version and sub-plugin metadata, .claude/settings.json configures hooks and permissions, .mcp.json declares MCP servers consumed by the agent, and run-mcp.sh is the launcher used for stdio servers. When the harness's deploy-validation surface is updated to consume the deploy plugin's contract directly, the changes flow through .mcp.json and .claude/settings.json rather than being hardcoded inside the harness — the explicit goal of issue #37. Source: .mcp.json, .claude/settings.json, run-mcp.sh

Active Development Threads

Several open issues shape the near-term architecture:

• #37 targets de-hardcoding the harness's deploy tool so its validation surface stays in sync with the deploy plugin.
• #36 tracks a future switch from hook-based delivery to claude/channel MCP push once stdio reliability improves upstream.
• #35 proposes folding repo_verify_changed and repo_health into repo_state once perception is proven in practice.
• #34 adds detection for external edits to files the agent is working on, using a perception_touched.json set hashed against watcher events.
• #33 adds CI status to the perception snapshot by reusing health._ci_check on a timed interval.

These threads share a common direction: push more state into the perception snapshot and reduce on-demand verb tools, so the agent reaches for fewer manual commands and repo_state becomes the single primary surface for repository awareness.

Related Pages

Related topics: Plugin Overview & System Architecture, Deployment, Drift Detection & Operations

Core Harness Tools, Serena Proxy & Workflow Skills

The repo_agent_harness package is the stdio MCP server that gives a coding agent repo-aware verbs without owning IDE state. It bundles four capability surfaces: a tool surface for foreground edits (server.py), a serena_gate adapter that brokers calls to the Serena LSP/MCP runtime, a perception / context layer (context.py, git.py) that pushes repo state into the prompt, and a set of analysis helpers for symbols and impact (symbols.py, impact.py). Version drift is currently zero on this plugin (v3.9.2 matches its manifest) and repo_bootstrap is already parametrized.

Core Harness Tools

server.py is the MCP tool registry. The verbs it exposes split into two families: bootstrap / perception (repo_bootstrap, repo_state, repo_verify_changed, repo_health) and action (repo_apply_patch, repo_commit, repo_deploy, plus the harness's deploy validation). The community is currently collapsing the on-demand verbs repo_verify_changed and repo_health into thin "force a refresh" wrappers over the backgrounded repo_state snapshot, because the underlying checks already run in the background daemon. Source: servers/harness-mcp/repo_agent_harness/server.py:1-1

A separate, parallel set of perception upgrades is in flight. CI status will be folded into the same repo_state snapshot by reusing health._ci_check (a gh run list call) on a timed interval, gated per-repo because it is a network call. External edits to files the agent has open will be detected by hashing the paths recorded in perception_touched.json and comparing against the watcher; on mismatch, the agent is warned. Both features are scoped in issues #33 and #34 and share the same daemon architecture.

Serena Proxy (serena_gate)

serena_gate.py is a thin adapter — not a full re-implementation of Serena. It exists because the harness is a stdio MCP server and the experimental claude/channel push transport is unreliable from stdio servers (anthropic/claude-code #45563, #36431), so delivery currently flows through Claude Code hooks rather than server-pushed channels. Source: servers/harness-mcp/repo_agent_harness/serena_gate.py:1-1

The gate translates a small set of harness verbs into Serena RPCs, caches symbol lookups, and surfaces failures as MCP tool errors. Once upstream fixes land, an optional flag-gated claude/channel capability will be added behind the same gate so the harness can opt into server-push delivery without restructuring consumers (issue #36).

Context, Git & Symbol Helpers

context.py builds the per-prompt digest that is injected via UserPromptSubmit. It currently renders branch, HEAD, merge-conflict status, and is the integration point for the upcoming CI conclusion and touched-set hash digest. git.py owns the actual git subprocess calls and the backgrounded watcher that feeds context.py. Source: servers/harness-mcp/repo_agent_harness/context.py:1-1, servers/harness-mcp/repo_agent_harness/git.py:1-1

symbols.py wraps the language-server symbol resolution that the serena_gate delegates into, and impact.py answers "what does this change break?" questions using those symbols plus the git index. Together they let repo_apply_patch preview blast radius before the agent commits a diff. Source: servers/harness-mcp/repo_agent_harness/symbols.py:1-1, servers/harness-mcp/repo_agent_harness/impact.py:1-1

Workflow Skills & Open Work

The harness today surfaces a deploy tool whose validation surface is drifted from the deploy plugin's actual contract, which is the motivation behind issue #37 ("De-hardcode the harness deploy tool"). The fix path is parametrization through the existing repo_bootstrap parameters rather than a new tool. Skill workflows that wrap repo_bootstrap → patch → impact → commit → deploy sit above this layer in the agent harness and are not part of the harness MCP package itself. Source: servers/harness-mcp/repo_agent_harness/server.py:1-1

The near-term direction is consolidation: one repo_state snapshot as the single source of truth, optional Channels capability behind a flag, external-edit detection, and CI status folded into the same digest.

Related Pages

Related topics: Core Harness Tools, Serena Proxy & Workflow Skills, Deployment, Drift Detection & Operations

Memory & Perception Layer (cognee ↔ claude-mem)

Purpose and Scope

The harness ships a two-track substrate for stateful operation. The memory track persists long-term recall via cognee and mirrors it into claude-mem so both stores stay in agreement. The perception track supplies in-band awareness of repository and environment changes (branch/HEAD switches, merge conflicts, CI status, external edits) so the agent doesn't reach for ad‑hoc shell tools.

v3.23.0 formalized the coexistence model behind a flag: writes are mirrored, the legacy on-the-wire client capture path is removed, and recall is gated off by default. The intent is to keep cognee as the canonical store while letting claude-mem serve hot conversational recall, without either side observing duplicate or conflicting state.

Source: servers/harness-mcp/repo_agent_harness/mem.py Source: PR #42 — feat(mem): cognee ↔ claude-mem coexistence (v3.23.0)

Memory: cognee ↔ claude-mem Coexistence

Topology

The cognee side is split into three narrow modules rather than one monolith:

mem.py is the only entry point agents call. It picks cognee_client vs cognee_local based on environment, then runs every write through cognee_sync so claude-mem observes the same event.

Source: servers/harness-mcp/repo_agent_harness/mem.py Source: servers/harness-mcp/repo_agent_harness/cognee_client.py Source: servers/harness-mcp/repo_agent_harness/cognee_local.py Source: servers/harness-mcp/repo_agent_harness/cognee_sync.py

What Changed in v3.23.0

Three behaviors were tightened, all reachable through mem.py:

1. Mirror, don't duplicate. Every recall-bearing write is broadcast to both backends via cognee_sync. Cognee remains the system of record; claude-mem is a read-through cache.
2. Remove client capture. The earlier design observed transcript text inside the cognee client transport. That capture has been excised so cognee_client.py is a pure network shim. Conversation capture is now claude-mem's responsibility.
3. Gate recall off by default. Recall is opt‑in via configuration. An agent that hasn't enabled it gets a no‑op mem.recall, avoiding surprise context inflation.

flowchart LR
  Agent[Agent / Tool call] --> Mem[mem.py facade]
  Mem --> Client{cognee daemon reachable?}
  Client -- yes --> CC[cognee_client.py]
  Client -- no --> CL[cognee_local.py]
  CC --> Sync[cognee_sync.py]
  CL --> Sync
  Sync --> CogDB[(cognee store)]
  Sync --> CmDB[(claude-mem store)]
  Sync -- gated recall --> Agent

Source: servers/harness-mcp/repo_agent_harness/mem.py Source: servers/harness-mcp/repo_agent_harness/cognee_sync.py

Perception: Repository Awareness

Perception runs as a background watcher that publishes a repo_state snapshot, which downstream surfaces (tool responses, UserPromptSubmit digest) consume.

Watcher Core

watcher.py is the filesystem watcher. It consumes the touched-set recorded by PostToolUse hooks (typically persisted to perception_touched.json) and wakes the perception loop when an interesting change lands — branch switches, HEAD moves, merge‑conflict markers, or external edits to files the agent is currently holding.

Source: servers/harness-mcp/repo_agent_harness/watcher.py Source: servers/harness-mcp/repo_agent_harness/perception.py

Snapshot and Tools

perception.py owns the periodic rebuild of repo_state and exposes the high-level verbs. The design intent — tracked in #35 — is to make repo_state the primary surface and demote repo_verify_changed / repo_health to thin "force a refresh" wrappers, since the daemon already runs the checks in the background.

Source: issue #35 — consolidate repo_verify_changed + repo_health into repo_state

Known Gaps Tracked as Issues

• External edits to in-flight files (#34): hash/mtime the touched‑set; alert when the watcher sees a change the agent didn't author.
• CI status in the snapshot (#33): reuse health._ci_check on a timed interval (network opt‑in) and surface the latest workflow conclusion in repo_state and the UserPromptSubmit digest, so the agent stops reaching for gh manually.
• Channels delivery upgrade (#36): the harness currently falls back to Claude Code hooks because claude/channel push is unreliable from stdio MCP servers. The upgrade path is flag-gated and waits on upstream fixes (anthropic/claude-code #45563, #36431).

Source: issue #34 — detect external edits Source: issue #33 — fold CI status into the perception snapshot Source: issue #36 — Channels delivery upgrade

How Memory and Perception Cooperate

A typical agent turn flows through both layers:

1. Perception watches the working set and keeps repo_state fresh.
2. The agent decides to recall context — mem.recall consults claude-mem first, falls back to cognee if needed, and is opt-in only.
3. A write goes through mem.write, which dispatches through cognee_client/cognee_local and is mirrored by cognee_sync.
4. On the next perceived repo-state change, perception rebuilds and the cycle continues.

This split — mem for facts, perception for "what's happening right now" — is the practical mental model for operating the harness today.

Source: servers/harness-mcp/repo_agent_harness/mem.py Source: servers/harness-mcp/repo_agent_harness/perception.py

Related Pages

Related topics: Plugin Overview & System Architecture, Memory & Perception Layer (cognee ↔ claude-mem)

Deployment, Drift Detection & Operations

The Deployment, Drift Detection & Operations subsystem is the operations backbone of the repo_agent_harness MCP server. It defines how the harness plugin is bootstrapped into a repository, how local reality is compared against the declared plugin manifest, how post-deploy sanity checks are executed, and how policy gates decide which operations are allowed. Together these modules form the closed loop that prevents silent version skew between the harness plugin and the consumer-facing deploy surface.

The subsystem is intentionally split into six cooperating modules so that each concern — bootstrap, drift, verification, health, repository detection, and policy — can evolve independently. Community tracking issue #37 ("T6 — De-hardcode the harness deploy tool") explicitly notes that repo_bootstrap is already parametrized, that the harness plugin has no version drift (v3.9.2 == manifest, 0 unreleased commits), but that the deploy-validation surface is drifted versus the deploy plugin's contract. The pages below address each concern in the order an operator typically encounters them.

Deploy Tooling and Bootstrap

deploy.py owns the lifecycle of bringing the harness plugin into a target repository. It exposes a repo_bootstrap entry point that, according to the issue context, is "already parametrized," meaning it accepts the target repo path, the plugin version, and the bootstrap mode rather than relying on hard-coded constants. The module is responsible for materializing plugin manifests, writing the harness entry under .harness/, and reporting the resolved versions back to the caller for downstream comparison.

drift.py is the counterweight to deploy.py. Whereas deploy.py writes state, drift.py reads it back and answers a single question: does what is on disk still match what the manifest claims? It compares the deployed plugin version against the manifest version, counts any unreleased commits in the plugin checkout, and emits a structured drift report. Issue #37 explicitly relies on drift.py to certify the harness plugin's "no version drift" property (v3.9.2 == manifest, 0 unreleased commits) before the deploy surface is allowed to advance. This is the primary mechanism by which the project blocks releases whose deploy-validation surface has drifted away from the deploy plugin's contract.

Verification, Health, and Detection

verify.py provides on-demand verification verbs that the agent (and human operators) can invoke to re-run drift and integrity checks synchronously. It typically consumes the output of drift.py and adds deeper checks such as file integrity, manifest schema conformance, and the presence of required bootstrap artifacts. Per issue #35 ("refactor(perception): consolidate repo_verify_changed + repo_health into repo_state"), the long-term direction is for repo_verify_changed to become a thin "force a refresh" wrapper around the continuously running repo_state perception snapshot — once the perception daemon is trusted, the on-demand verbs become force-refresh affordances rather than primary surfaces.

health.py complements verify.py with continuous, polling-style checks: repository reachability, working-tree cleanliness, hook liveness, and — per issue #33 ("feat(perception): fold CI status into the perception snapshot") — the _ci_check helper that calls gh run list to fetch the latest workflow conclusion. The plan is to reuse _ci_check on a timed interval so that CI status appears in repo_state and in the UserPromptSubmit digest, removing the need for the agent to reach for gh manually. The _ci_check is network-dependent and is therefore gated behind per-repo opt-in.

detect.py identifies the repository under the harness's working directory: it infers the owner, remote URL, default branch, and whether the repo is a fork, a worktree, or a submodule. All upstream modules (drift.py, verify.py, health.py) consume the output of detect.py so they can scope their work correctly — drift against the right remote, verification against the right working tree, and health probes against the right hooks.

Policy Gating

policies.py is the gatekeeper that decides which deploy, drift, verify, and health operations are permitted in a given context. It evaluates declarative rules — for example, "block repo_bootstrap against a dirty working tree" or "require zero drift before repo_deploy can proceed" — and returns a structured allow/deny result that the calling tool surfaces to the agent. By centralizing policy, the harness keeps deploy.py and drift.py free of conditional logic that would otherwise leak across modules.

Data Flow and Module Boundaries

flowchart LR
    A[detect.py<br/>repo introspection] --> B[deploy.py<br/>repo_bootstrap]
    A --> C[drift.py<br/>version diff]
    B --> C
    C --> D[verify.py<br/>on-demand checks]
    C --> E[health.py<br/>continuous probes]
    P[policies.py] --> B
    P --> C
    P --> D
    P --> E
    D --> F[(repo_state<br/>perception snapshot)]
    E --> F

The flow above reflects the current architecture and the consolidation planned in issue #35: detect.py seeds context, deploy.py writes state, drift.py measures skew, and verify.py/health.py push results into the unified repo_state perception surface, all under the supervision of policies.py.

Operational Notes

• The harness plugin is intentionally pinned: the "no version drift" baseline (v3.9.2 == manifest) is the gate that keeps the deploy-validation surface honest, per issue #37.
• _ci_check in health.py is opt-in per repository because it requires network access and a configured gh CLI.
• As perception matures, repo_verify_changed and repo_health are expected to become thin wrappers that force-refresh repo_state rather than independent verification paths, per issue #35.
• Any change to deploy semantics must be paired with a corresponding drift.py and policies.py update; otherwise the validation surface will silently desynchronize from the deploy surface — the exact failure mode issue #37 is designed to prevent.

Source: servers/harness-mcp/repo_agent_harness/deploy.py:1-1, servers/harness-mcp/repo_agent_harness/drift.py:1-1, servers/harness-mcp/repo_agent_harness/verify.py:1-1, servers/harness-mcp/repo_agent_harness/health.py:1-1, servers/harness-mcp/repo_agent_harness/detect.py:1-1, servers/harness-mcp/repo_agent_harness/policies.py:1-1

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/astrojones/astrojones

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/astrojones/astrojones

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/astrojones/astrojones

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/astrojones/astrojones

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/astrojones/astrojones

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/astrojones/astrojones

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/astrojones/astrojones

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using astrojones-mcp-retrieval with real data or production workflows.

• Configuration risk requires verification - GitHub / issue