@x12i/agengit

Git-like control for agent state.

@x12i/agengit is a TypeScript library and CLI for snapshotting, committing, diffing, releasing, deploying, rolling back, querying, auditing, and explaining the full state of an AI agent.

Agengit treats an agent as a governed repository of agent state: configuration, prompts, skills, capabilities, files, directories, registries, evals, runtime pointers, static metadata, and data-backed components.

The central object is now the capability.

A capability is a complete agent behavior unit. It can contain instructions, rules, context, knowledge, schemas, examples, evals, tools, permissions, policies, workflows, runtime assumptions, memory assumptions, risk metadata, provenance, and bindings.

Agengit does not package or distribute capabilities. That is the role of package managers such as Agentix. Agengit governs the same capability content as agent state: it versions it, diffs it, releases it, deploys it, rolls it back, and explains what exact capability content existed at runtime.

Agentix packages capability content.
Agengit governs capability content as agent state.

Same content model.
Different lifecycle responsibility.

Why agengit exists

Code has Git.

Reusable code packages have npm.

Agents need the same split:

| Layer | Code world | Agent world | | ----------------------------- | ---------- | ------------------------------------ | | Versioning / state governance | Git | agengit | | Reusable dependency packages | npm | Agentix / capability package systems |

Agengit is the Git-like layer for agents.

It answers:

What changed in this agent?
Which capability content was added, removed, or modified?
What was committed?
What was released?
What reached production?
Can we roll back?
Which exact instructions, rules, tools, permissions, policies, knowledge, runtime profile, and evals were active when a run happened?

Core concepts

Agent repository

An agent repository is a workspace managed by .agengit/.

It contains the files, components, capabilities, policies, releases, environments, and runtime records that define an agent.

Component

A component is a tracked part of the agent state.

Components may be:

| Kind | Meaning | | ------------ | ------------------------------------------------------------ | | file | One tracked file under the repo | | directory | A tracked directory tree with optional include/exclude globs | | metagit | A metagit-backed repository at repoPath | | registry | A static or external registry reference | | eval | Eval component or eval result source | | static | Static metadata | | capability | First-class capability content | | runtime | Runtime profile or active runtime pointer | | policy | Policy/governance component | | knowledge | Knowledge source, bundle, index, or external reference |

Capability

A capability is a first-class agent-state object.

Examples:

refund.resolve
refund.escalate
ticket.create
pii.safeAction
hrPolicy.answer
risk.triage
support.qualityEval
lowRiskSupportRuntime

A capability may be local, generated, catalog-backed, package-backed, template-backed, or manually authored. Agengit records the source, but does not own package installation or distribution.

Capability binding

A capability can exist in the repo without being active.

A binding activates a capability for an agent, environment, route, task type, workflow, or runtime scope.

This lets agengit distinguish:

Capability exists.
Capability is active in this agent state.

Capability BOM

Every release can include a Capability Bill of Materials.

The BOM records the exact active capabilities, hashes, assets, tools, permissions, policies, knowledge, runtime assumptions, and risk metadata included in a release.

Runtime provenance

Every recorded run can be explained against the exact release and capability state that was active when the run happened.

Install

npm install @x12i/agengit

Node.js: >=20 (aligned with @x12i/metagit 2.x) Module format: ESM

Optional / peer-related packages

| Package | Role | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | @x12i/metagit | Dependency for kind: "metagit" components. Snapshot and diff use the library; deploy plan/apply and rollback invoke the metagit CLI (release create, deploy, rollback) in each component repoPath with --json. Requires @x12i/metagit ≥ 2.0.5. | | express | Optional peer. Only needed when using createAgengitExpressMiddleware from @x12i/agengit/server/express. |

Capability content model

Agengit supports capabilities as first-class state.

A capability can contain:

Capability
├─ identity / metadata
├─ instructions
├─ rules
├─ context
├─ knowledge
├─ schemas
├─ examples
├─ evals
├─ tools
├─ permissions
├─ policies
├─ workflow
├─ runtime
├─ memory assumptions
├─ risk / governance
├─ provenance / source
└─ bindings / activation

Capability identity

export interface AgentCapability {
  id: string;
  name: string;

  type:
    | "skill"
    | "toolkit"
    | "policy"
    | "eval"
    | "knowledge"
    | "workflow"
    | "template"
    | "runtime"
    | "memory"
    | "other";

  description?: string;
  version?: string;
  status?: "draft" | "active" | "deprecated" | "blocked" | "archived";

  instructions?: CapabilityInstruction[];
  rules?: CapabilityRule[];
  context?: CapabilityContext[];
  knowledge?: CapabilityKnowledge[];
  schemas?: CapabilitySchema[];
  examples?: CapabilityExample[];
  evals?: CapabilityEval[];
  tools?: CapabilityTool[];
  permissions?: CapabilityPermission[];
  policies?: CapabilityPolicy[];
  workflow?: CapabilityWorkflow;
  runtime?: CapabilityRuntime;
  memory?: CapabilityMemoryAssumption[];

  risk?: CapabilityRisk;
  governance?: CapabilityGovernance;
  provenance?: CapabilityProvenance;

  contentHash: string;
  metadata?: Record<string, unknown>;
}

Capability asset

Most capability parts are represented as normalized assets.

export interface CapabilityAsset {
  id: string;
  name: string;

  kind:
    | "instruction"
    | "rule"
    | "context"
    | "knowledge"
    | "schema"
    | "example"
    | "eval"
    | "tool"
    | "permission"
    | "policy"
    | "workflow"
    | "runtime"
    | "memory"
    | "other";

  path?: string;
  format?: "markdown" | "json" | "yaml" | "text" | "external-ref" | "binary";

  content?: unknown;
  contentHash: string;

  required?: boolean;
  scope?: "shared" | "capability" | "agent" | "environment";

  metadata?: Record<string, unknown>;
}

Instructions

Instructions describe what the agent should do.

Examples:

assess refund eligibility
explain decision politely
use tool only after verification
do not promise refund before approval

Instruction types:

task
behavior
tone
decision
tool-use
response
safety
other

Rules

Rules are constraints, decision logic, routing logic, guardrails, and approval requirements.

Rule types:

business
safety
approval
routing
decision
guardrail
compliance
other

Example diff:

Rules:
  ~ refund-window.rules.json
    approval threshold changed:
      before: 90 days
      after: 60 days

Context

Context is compact grounding material directly attached to the capability.

Examples:

refund-policy-summary.md
refund-edge-cases.md
customer-support-tone.md

Context is different from knowledge.

context = compact material attached to the capability
knowledge = larger reference material, corpus, index, or external source

Knowledge

Knowledge can represent documents, document bundles, RAG indexes, chunk sets, URLs, external stores, databases, or other knowledge sources.

export interface CapabilityKnowledge {
  id: string;
  name: string;

  sourceType:
    | "document"
    | "document-bundle"
    | "rag-index"
    | "chunk-set"
    | "external-store"
    | "url"
    | "database"
    | "other";

  sourceUri?: string;
  path?: string;

  contentHash?: string;
  indexHash?: string;
  chunkHash?: string;

  retrieval?: {
    enabled: boolean;
    strategy?: string;
    topK?: number;
    filters?: Record<string, unknown>;
  };

  metadata?: Record<string, unknown>;
}

Schemas

Schemas define contracts.

Schema types:

input
output
tool-input
tool-output
event
state
memory
intermediate
other

Supported schema formats:

json-schema
zod
typescript
openapi
other

Examples

Examples shape behavior. They are not evals.

Example types:

few-shot
golden
edge-case
bad-example
counter-example
other

Evals

Evals test behavior and may become deployment gates.

Eval types:

regression
quality
safety
policy
schema
tool-use
other

Evals may include latest result metadata:

{
  status: "passed" | "failed" | "not-run" | "unknown";
  runId?: string;
  passedAt?: string;
  score?: number;
}

Tools

Tools describe callable external actions or functions.

export interface CapabilityTool {
  id: string;
  name: string;

  provider?: string;
  operation?: string;

  inputSchema?: string;
  outputSchema?: string;

  required?: boolean;

  constraints?: {
    readOnly?: boolean;
    requiresApproval?: boolean;
    allowedResources?: string[];
  };

  metadata?: Record<string, unknown>;
}

Permissions

Permissions define what a capability is allowed to do.

export interface CapabilityPermission {
  id: string;

  permission: string;

  level:
    | "read"
    | "write"
    | "admin"
    | "external-action"
    | "unknown";

  resource?: string;
  action?: string;

  required?: boolean;
  reason?: string;

  requiresApproval?: boolean;
  approvalType?: "security" | "compliance" | "business-owner" | "platform";

  metadata?: Record<string, unknown>;
}

Example:

write:refund-request
read:customer
write:crm
external-action:send-email

Policies

Policies are active constraints over behavior, data, approvals, deployment, and runtime conduct.

Policy types:

safety
compliance
pii
approval
data-handling
tool-use
deployment
other

Enforcement modes:

advisory
warning
blocking
runtime
deployment

Workflow

A workflow capability contains steps, transitions, branching, approvals, handoffs, retrieval steps, eval steps, and tool calls.

export interface CapabilityWorkflow {
  id: string;
  name: string;

  steps: CapabilityWorkflowStep[];
  transitions?: CapabilityWorkflowTransition[];

  entryStepId?: string;
  metadata?: Record<string, unknown>;
}

Runtime

Runtime assumptions define how the capability expects to run.

Examples:

model profile
routing profile
temperature
tool mode
retrieval mode
fallback strategy

Memory assumptions

Memory assumptions define whether a capability reads or writes session, user, organization, task, or long-term memory.

This is separate from knowledge.

knowledge = reference material
memory = changing agent/user/session/task state

Risk and governance

Capabilities can carry risk metadata.

Risk levels:

low
medium
high
critical
unknown

Risk categories:

financial-action
data-access
external-action
security
compliance
privacy
destructive-action
other

Governance can define approval requirements, allowed environments, blocked environments, deprecation, blocking, and review status.

Provenance

Agengit records where capability content came from without owning the source system.

Source types:

local
package
generated
catalog
template
remote
database
manual
unknown

This lets package-originated content be represented as sourceType: "package" while agengit remains a state-governance engine, not a package manager.

Recommended workspace shape

Agengit does not force one folder structure, but this layout is recommended:

support-agent/
├─ agent.json
├─ prompts/
├─ policies/
├─ runtime/
├─ data/
├─ capabilities/
│  ├─ refund.resolve/
│  │  ├─ capability.json
│  │  ├─ instructions/
│  │  ├─ rules/
│  │  ├─ context/
│  │  ├─ knowledge/
│  │  ├─ schemas/
│  │  ├─ examples/
│  │  └─ evals/
│  └─ pii.safeAction/
│     ├─ capability.json
│     ├─ rules/
│     └─ evals/
└─ .agengit/
   ├─ config.json
   ├─ components.json
   ├─ capabilities.json   # optional `bindings` array lives here (v1); separate bindings file is a possible future layout
   ├─ environments.json
   ├─ policies.json
   ├─ commits/
   ├─ releases/
   ├─ deployments/
   └─ runs/

CLI

Run via:

npx @x12i/agengit ...

or:

agengit ...

after installation.

Core commands

| Command | Description | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | agengit clone <url> [directory] | git clone, then open the directory as an agengit repo if .agengit exists. | | agengit init --agent <id> | Initialize .agengit/. | | agengit status | Show repo, component, policy, eval, and capability status. | | agengit snapshot | Create a JSON snapshot of all tracked agent state. | | agengit commit -m <msg> | Snapshot, validate, evaluate gates, and persist a commit. | | agengit diff | Compare two commits or live state vs HEAD. | | agengit log | Show commit log. | | agengit show <commit> | Show commit details. | | agengit component add \| list \| show \| remove | Manage tracked components. | | agengit capability add \| list \| show \| remove \| bind \| unbind | Manage capability state and active bindings. | | agengit query capabilities | Query the capability index. | | agengit validate | Validate repo state. | | agengit env add \| list \| active | Manage environments and runtime pointers. | | agengit release create \| list \| show \| bom | Manage immutable releases; BOM is printed via bom or embedded in show. | | agengit deploy plan \| apply | Plan/apply deployment to an environment. | | agengit rollback plan \| apply | Plan/apply rollback. | | agengit run | Record a run. | | agengit explain <runId> | Explain runtime provenance; --no-capabilities omits capability fields. |

What the agengit binary ships today

The CLI in this repo includes: clone, init, component (add, list, show, remove), capability (add, list, show, remove, bind, unbind), env (add, list, active), status (optional --capabilities), snapshot, commit, diff (optional --capabilities; --live supported), log, show <commit> (optional --capabilities), validate (optional --capabilities for capability-state checks), release (create, list, show with optional --capabilities, bom), deploy (plan, apply), rollback (plan, apply), run, explain (includes capability provenance by default; --no-capabilities to omit), and query capabilities (filters: --type, --permission, --tool, --schema, --risk, --knowledge). Capability discovery uses .agengit/capabilities.json (schemaVersion: agengit.capabilities.v1); bindings live in the same file under bindings (no separate capability-bindings.json in v1).

Not in the CLI yet: agengit release diff …. Compare two releases by taking each release’s commit from agengit release show <id> and running agengit diff --from <c1> --to <c2> [--capabilities].

Live checks for docs/extent-agengit.md FR-1–FR-30 run with npm run test:live (tests/live/extent-frs.test.ts).

CLI examples

Initialize an agent repo

agengit init --agent support-agent --repo-name support-agent

Add tracked components

# Metagit-backed data plane
agengit component add knowledge-db \
  --kind metagit \
  --role knowledge \
  --repo-path ./metagit/knowledge-db \
  --metagit-source-env dev

# Plain JSON file
agengit component add catalog \
  --kind file \
  --role knowledge \
  --path ./data/catalog.json \
  --required

# Directory tree with glob scope
agengit component add rag-files \
  --kind directory \
  --role rag-data \
  --path ./corpus \
  --include "**/*.md,**/*.json" \
  --exclude "**/draft/**"

Add a capability

agengit capability add refund.resolve \
  --type skill \
  --path ./capabilities/refund.resolve/capability.json

Bind a capability to the agent

agengit capability bind refund.resolve \
  --as support.refunds.resolve \
  --permission write:refund-request \
  --tool payments.createRefundRequest

Check status

agengit status

Example output:

Agent: support-agent
HEAD: agc_8d91c

Components:
  catalog          clean
  rag-files        changed
  knowledge-db     clean

Capabilities:
  active: 7
  changed: 2
  new high-risk: 1
  new permissions: 1

Changed:
  + refund.resolve
  ~ pii.safeAction

Validation:
  0 errors
  1 warning

Capability-aware diff

agengit diff --live --capabilities

Example output:

Capability changes

+ Capability added:
  refund.resolve
  type: skill
  risk: high

  Instructions:
    + assess-eligibility.md
    + decide-refund.md

  Rules:
    + refund-window.rules.json

  Schemas:
    + RefundDecision

  Evals:
    + refund-regression-suite

  Tools:
    + payments.createRefundRequest

  Permissions:
    + write:refund-request

~ Capability changed:
  pii.safeAction
  type: policy

  Rules:
    ~ pii-redaction-threshold
      severity changed: warning → blocker

- Capability removed:
  legacy.ticket.create

Validate capability state

agengit validate --capabilities

Validation checks:

- every capability has id, name, type, and contentHash
- every active binding points to an existing capability
- every referenced instruction exists
- every referenced rule exists and is valid
- every context item exists
- every knowledge reference resolves or has a source hash
- every schema is valid
- every required eval exists
- every required tool is declared
- every required permission is declared
- every policy reference resolves
- every workflow step references valid assets/tools/permissions
- every runtime profile is valid
- every memory schema reference resolves
- every risk-bearing capability has risk metadata
- every hash is deterministic and current

Commit

agengit commit -m "add refund resolution capability"

Example commit summary:

Commit: add refund resolution capability

Capability changes:
  + refund.resolve
    type: skill
    risk: high
    permission: write:refund-request
    tool: payments.createRefundRequest

Create a release

agengit release create support-agent-v12 --commit HEAD

Show release Capability BOM

agengit release bom support-agent-v12

Example:

Capability BOM: support-agent-v12

Capabilities:
  refund.resolve
    type: skill
    hash: sha256-capability-123
    risk: high
    tools:
      payments.createRefundRequest
    permissions:
      write:refund-request

  pii.safeAction
    type: policy
    hash: sha256-policy-456
    enforcement:
      deployment

Compare release capabilities

There is no agengit release diff subcommand yet. Compare the commits pinned by each release:

agengit release show support-agent-v11 --capabilities   # note .commit
agengit release show support-agent-v12 --capabilities
agengit diff --from <commitV11> --to <commitV12> --format text --capabilities

Example (illustrative output shape for capability-aware diff text):

Capability diff (v11 → v12)

Added:
  refund.resolve
    risk: high
    permission: write:refund-request

Changed:
  pii.safeAction
    rule changed: pii-redaction-threshold

Removed:
  legacy.ticket.create

Deployment plan

agengit deploy plan --release support-agent-v12 --to production

Capability gates are evaluated during deployment planning.

Example:

Deployment plan: production

Capability gates:

✓ Capability BOM verified
✓ Required policy capability present: pii.safeAction
✓ Required eval capability passed: support-quality-regression

✕ New high-risk capability requires approval:
  refund.resolve
  risk: high
  permission: write:refund-request

Deployment blocked.

Apply deployment

agengit deploy apply --plan-hash <planHash> --confirm

Rollback

agengit rollback plan --to support-agent-v11
agengit rollback apply --plan-hash <planHash> --confirm

Example rollback plan:

Rollback plan

Current release:
  support-agent-v12

Target release:
  support-agent-v11

Capability changes:
  - refund.resolve @ sha256-new
  + refund.resolve @ sha256-old

Permissions removed:
  write:refund-request

Runtime restored:
  low-risk-support-runtime @ sha256-old

Explain a run

agengit explain run_123
# Omit capability block from JSON:
agengit explain run_123 --no-capabilities

Example:

Run provenance

Run:
  run_123

Agent:
  support-agent

Release:
  support-agent-v12

Capabilities active at runtime:

  refund.resolve
    type: skill
    hash: sha256-capability-123
    instructions:
      assess-eligibility sha256-i1
      decide-refund sha256-i2
    rules:
      refund-window sha256-r1
    schemas:
      RefundDecision sha256-s1
    tools:
      payments.createRefundRequest
    permissions:
      write:refund-request

  pii.safeAction
    type: policy
    hash: sha256-policy-456

Query capabilities

agengit query capabilities --type policy
agengit query capabilities --permission write:refund-request
agengit query capabilities --tool payments.createRefundRequest
agengit query capabilities --schema RefundDecision
agengit query capabilities --risk high
agengit query capabilities --knowledge hr-policy

Metagit components

kind: "metagit" means a metagit repository on disk at repoPath.

Agengit delegates to @x12i/metagit as follows:

snapshot / HEAD / live diff / commit-to-commit diff → metagit library (open repo at repoPath)
deploy plan / deploy apply / rollback plan / rollback apply → metagit CLI in that repo (--json)

For deploy plan, agengit runs metagit release create <releaseName> --commit <pin> --from <sourceEnv> then metagit deploy plan --release <releaseName> --to <targetEnv>. Configure metagitSourceEnvironment (or legacy environment) on the component so --from matches a pipeline environment name in .metagit/pipeline.json. Target names passed to agengit deploy … --to must match the same keys metagit uses (override config path with METAGIT_PIPELINE_CONFIG when CI generates pipeline JSON). Optional metagitReleaseName fixes the metagit release label; otherwise agengit derives one from the agent release id and component id.

Protected metagit environments may prompt for typed confirmation on apply; agengit forwards the confirm string from deploy apply to satisfy metagit when required. Rollback apply forwards the metagit deployment id when metagit prompts.

Use metagit release-bundle at the workspace level when several metagit repos deploy together; agengit still orchestrates per-agent deploy records.

Version pins in agengit commits are metagit commit ids, with disk-ref fallbacks when metagit cannot open.

Use kind: "file" or kind: "directory" for arbitrary local files or folders that should be hashed and versioned directly by agengit.

Use metagit when the component is itself a metadata/database repository.

Use capability state when the content represents agent behavior.

Client migration: @x12i/metagit 2.x and deploy

• Node: Use Node 20+ in CI and production (matches @x12i/metagit engines).
• Components: Every kind: "metagit" component used in deploy plan must set metagitSourceEnvironment or environment so agengit can run metagit release create … --from <env> (pipeline env name from .metagit/pipeline.json).
• Environment names: Agengit deploy --to <env> must use the same names as metagit pipeline environments (or set METAGIT_PIPELINE_CONFIG to the pipeline file CI generates).
• Plans: Deploy plans now persist metagitReleaseName plus the metagit plan payload; re-plan if you see errors about a missing release name.
• Regression fixed: Older integrations against metagit 2.x could silently skip Mongo promotion (pointer-only) because repo.deploy no longer exists on the library; current code runs the metagit CLI instead.

Programmatic API

Facade

import { agengit, VERSION } from "@x12i/agengit";

await agengit.init({
  cwd,
  agentId: "support-agent",
  storage: { driver: "local" }
});

const repo = await agengit.open({ cwd });

const status = await repo.status();
const snapshot = await repo.snapshot();
const diff = await repo.diff({ live: true, capabilities: true });

const commit = await repo.commit({
  message: "add refund resolution capability"
});

const release = await repo.release.create({
  name: "support-agent-v12",
  commit: commit.id
});

const plan = await repo.deploy.plan({
  releaseId: release.id,
  to: "production"
});

Main repo surface

| Area | Methods | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Workspace | status(), snapshot(), commit(), diff(), log(), queryCapabilities(); persisted commits are not a dedicated repo.show()—use CLI agengit show <hash> or read .agengit/commits/<hash>.json | | Components | components.add, components.remove, components.list, components.get, components.resolve | | Capabilities | Programmatic surface is queryCapabilities() on the repo. Manifest edits (add/remove/bind) are via CLI agengit capability … or @x12i/agengit/capabilities (writeCapabilitiesManifest, loaders, validateCapabilityStateFull, diffCapabilities, …). | | Releases | release.create, release.list, release.show, release.delete. A release’s BOM is the capabilityBom field on the object returned from release.show (CLI: release bom). | | Environments | env.add, env.list, env.get, env.remove, env.getActiveRelease, env.setActiveRelease | | Deploy | deploy.plan, deploy.apply, deploy.log | | Rollback | rollback.plan, rollback.apply | | Runs | runs.record, runs.explain, runs.get | | Policies | policies.evaluateForStatus only on the public repo type. Commit-time policy checks run inside commit(); deploy-time checks inside deploy.plan() / related deploy code—not separate evaluateForCommit / evaluateForDeploy methods on repo.policies. |

Capability API

Import from:

import {
  AgentCapability,
  CapabilityAsset,
  CapabilityBinding,
  CapabilityBom,
  CapabilityDiff,
  hashCapability,
  validateCapabilityState,
  validateCapabilityStateFull,
  diffCapabilities,
  createCapabilityBom,
  buildCapabilityIndex,
  evaluateCapabilityDeployGates,
  explainRunCapabilities
} from "@x12i/agengit/capabilities";

Hashing

const hash = hashCapability(capability);

Hashes are deterministic. Agengit normalizes ordering before hashing.

Validation

const issues = validateCapabilityState(capabilities, bindings);
// Repo-root file checks (hashes, assets on disk, binding requirements, …):
const fullIssues = validateCapabilityStateFull(repoRoot, capabilities, bindings);

Diff

const diff = diffCapabilities(beforeCapability, afterCapability);

BOM

const bom = createCapabilityBom(capabilities, bindings, { releaseId, commitId });

Index

const index = buildCapabilityIndex({
  capabilities,
  bindings
});

The index supports lookup by:

type
instruction
rule
context
knowledge
schema
eval
tool
permission
policy
runtime
risk

Subpath exports

| Import path | Contents | | ------------------------------ | ------------------------------------------------------------------------ | | @x12i/agengit | Main library, repo API, types | | @x12i/agengit/capabilities | Capability model, hashing, validation, diff, BOM, deploy gates, query helpers; published package also ships schemas/*.schema.json at package root (not a separate import path) | | @x12i/agengit/runtime | Runtime helpers such as loadActiveState and readLocalPointerFile | | @x12i/agengit/server | HTTP router factories | | @x12i/agengit/server/express | Express middleware |

HTTP server

Routes are defined without a built-in prefix. Mount the handler at /agengit, or strip your mount prefix before calling the router.

Node http

import { createServerRouter } from "@x12i/agengit/server";
import http from "node:http";

const handler = createServerRouter({ cwd: process.cwd() });

http
  .createServer((req, res) => {
    if (!req.url?.startsWith("/agengit")) {
      res.statusCode = 404;
      res.end();
      return;
    }

    req.url = req.url.slice("/agengit".length) || "/";
    void handler(req, res);
  })
  .listen(3000);

Express

import express from "express";
import { createAgengitExpressMiddleware } from "@x12i/agengit/server/express";

const app = express();

app.use(
  "/agengit",
  createAgengitExpressMiddleware({
    cwd: process.cwd()
  })
);

REST overview

These routes match createServerRouter in @x12i/agengit/server today. Capability CRUD, release BOM-only, and release-diff endpoints are not exposed over HTTP yet—use the CLI or the library (@x12i/agengit, @x12i/agengit/capabilities).

| Method | Path | Notes | | -------- | ------------------------------------ | ----- | | GET | /health | | | GET | /repo | | | GET | /status | | | POST | /snapshot | JSON body: optional runEvals, autoCommitMetagit, autoPushMetagit | | GET | /components | | | POST | /components | JSON body: full component definition | | DELETE | /components/:id | | | GET | /commits | Query: limit, componentId, since, author | | POST | /commits | JSON body: message, optional author, runEvals | | GET | /diff | Query: from, to, format, includeComponentDetails | | GET | /diff/live | Query: format, includeComponentDetails | | GET | /releases | | | POST | /releases | JSON body: releaseId, optional commit, message, sourceEnvironment | | GET | /releases/:id | Full release JSON (includes capabilityBom when present) | | DELETE | /releases/:id | | | GET | /environments | | | POST | /environments | JSON body validated by environmentCreateSchema | | GET | /environments/:name/active-release | | | POST | /deploy/plan | | | POST | /deploy/apply | | | GET | /deploy/log | Query: limit | | POST | /rollback/plan | | | POST | /rollback/apply | | | POST | /runs | | | GET | /runs/:id | | | GET | /runs/:id/explain | Does not yet mirror CLI --no-capabilities; always includes capability fields when present |

Runtime helper

import { loadActiveState, readLocalPointerFile } from "@x12i/agengit/runtime";

const active = await loadActiveState({
  cwd: process.cwd(),
  environment: "dev"
});

// active.commit
// active.releaseId
// active.commitPayload
// active.releasePayload
// active.capabilityBom
// active.capabilities

Runtime helpers are intended for agent runtimes that need to load the currently deployed state for a given environment.

Deployment gates

Agengit deployment planning evaluates both generic repo checks and capability-aware gates.

Built-in deployment checks include:

outer repo cleanliness
component status blockers
target commit validity
eval summary
protected environment confirmation
pre-deploy snapshot requirement
metagit pushed/drift rules for production-like environments
capability validation
capability BOM verification
capability risk gates
capability permission gates
capability policy gates
capability eval gates
capability runtime change gates
capability knowledge change visibility

Capability-specific gates include:

- Capability BOM exists.
- Capability hashes match release state.
- No active capability has invalid state.
- New high-risk capabilities require approval evidence.
- New write/admin/external-action permissions require approval evidence.
- Removed policy capabilities require explicit approval.
- Changed policy capabilities require review.
- Changed runtime capabilities require review.
- Changed schemas used by active capabilities require compatibility check.
- Required evals exist.
- Required evals passed.
- Deprecated capabilities are warned or blocked by policy.
- Blocked capabilities cannot deploy.
- Knowledge changes are visible in the plan.
- Workflow changes with approval/action steps are highlighted.

Storage

All agengit state lives under .agengit/ with:

{
  "storage": {
    "driver": "local"
  }
}

Remote data tiers and sync are handled by metagit and the surrounding deployment stack, not by agengit writing directly to object storage.

Runtime pointers use driver: "file" and point to active release/commit JSON files under the repo.

Configuration files

| File | Role | | ----------------------------------- | ------------------------------------------------------------------ | | .agengit/config.json | Agent id, repo name, default branch, storage config, package hints | | .agengit/components.json | Component definitions | | .agengit/capabilities.json | Capability registry for the agent repo | | .agengit/capability-bindings.json | Active capability bindings | | .agengit/environments.json | Named environments and runtime pointers | | .agengit/policies.json | Commit/deploy/status policy rules | | .agengit/commits/ | Commit records | | .agengit/releases/ | Release records and capability BOMs | | .agengit/deployments/ | Deployment plans and apply records | | .agengit/runs/ | Runtime provenance records |

Scripts

| Script | Description | | -------------------- | ------------------------------------------ | | npm run build | Compile src/ to dist/ | | npm run typecheck | Run TypeScript checks without emitting | | npm test | Typecheck, unit tests, and package dry-run | | npm run test:live | Build and run live integration tests | | npm run pack:check | Run package dry-run only |

Live tests

Copy .env.example to .env.

Suites are skipped when required environment variables are missing, so npm test stays credential-free.

MongoDB

| Variable | Required | Purpose | | ----------- | --------------- | ------------------------------------------------ | | MONGO_URI | For Mongo suite | MongoDB connection string. Alias: MONGODB_URI. |

The live Mongo suite creates a temporary database named:

agengit_vitest_<timestamp>_<random>

It runs a small read/write flow and drops the database in afterAll.

Optional:

AGENGIT_LIVE_TEST_NAMESPACE

can prefix live test agentId values.

Relationship to capability package managers

Agengit does not search registries, install packages, publish packages, upgrade packages, or manage dependency trust lifecycles.

That is outside the agengit boundary.

Agengit supports the resulting capability content as state.

A package manager may produce capability files, lockfiles, resolved assets, or generated capability manifests. Agengit can track those files and normalize the resulting capabilities, but package management remains outside agengit.

The boundary is:

Package manager:
  publish
  install
  use
  upgrade
  dependency graph
  registry
  package trust lifecycle

Agengit:
  state
  diff
  commit
  release
  deploy
  rollback
  query
  runtime provenance

License

MIT — see LICENSE. `