Hoplon

Agent-agnostic repository boundaries and focused context for AI coding agents and the humans who direct them.

Give agents freedom without giving up control.

Hoplon sits between an agent and a repository. A human or host declares what the agent may inspect and modify; Hoplon supplies structured reads, supervised edits, content-addressed snapshots, deterministic audits, recovery, and machine-readable evidence.

Hoplon began as the repository boundary for Project Phalanx. It is intentionally standalone and contains no model-specific decision logic. Any model can use it through an MCP-capable host; local TypeScript, CLI, HTTP, and gRPC surfaces let other hosts use the same contracts without adopting Phalanx.

Developer preview: the deterministic core and shipped transports are usable today, but the public API is still on the 0.4.x line. Expect additive growth and clearly documented compatibility changes before 1.0.

Why Hoplon

Agentic coding can waste context and reviewer time long before a test fails. Hoplon moves mechanical questions to the repository boundary and gives teams:

• Less unnecessary context. Structural templates, AST-bounded slices, and exact targeted reads avoid treating every task as a full-file or full-repo prompt. Estimated token telemetry makes that context reduction visible.

• Clear edit boundaries. Writable manifests declare the files and symbols an agent may change, and deterministic audits compare the result with the contract.

• Recoverable attempts. Content-addressed snapshots, rollback templates, repair context, and revert operations keep failed work from becoming ambiguous cleanup.

• Better human oversight. Review payloads and proof bundles show what changed, what passed, what blocked, and which evidence is advisory.

• Portable agent infrastructure. The same boundary works across models and orchestration stacks through MCP, TypeScript, CLI, HTTP, and gRPC.

The result is typed evidence backed by snapshots and AST checks, not an agent summary that the host must trust. These guarantees apply to supported operations routed through Hoplon; Hoplon is a repository-boundary engine, not an OS sandbox for separately granted filesystem or shell access.

Related MCP server: safe-code-mcp

What ships

Hoplon does not choose models, execute arbitrary shell commands, own retry policy, or replace tests and human review.

Quick start

Requirements: Git and Node.js 22 or newer.

git clone https://github.com/justguy/hoplon.git
cd hoplon
npm ci
npm run build
node dist/bin/hoplon.js status \
  --root . \
  --grammars-dir vendor/grammars \
  --format human

Run the executable boundary example:

npm run example:bounded-edit

It creates an isolated temporary repository, accepts an edit inside the declared symbol boundary, blocks an out-of-scope symbol, reverts the workspace, and prints the evidence returned by the real session path.

For development proof:

npm run typecheck
npm run test:arch
npm run test:contracts
npm run test:proof

The contract

A writable manifest is the boundary a human or host gives the agent:

const manifest = {
  manifestSchemaVersion: 2,
  projectId: 'widget',
  runId: 'run-42',
  correlationId: 'change-price-format',
  entries: [
    {
      path: 'src/format.ts',
      intent: 'modify',
      scope: { kind: 'symbols', symbols: ['formatPrice'] },
    },
  ],
};

The normal supervised loop is:

read with provenance
  -> declare manifest
  -> preflight
  -> snapshot
  -> dry-run (optional)
  -> apply or declare edits
  -> audit
       PASS  -> review/evidence -> close
       BLOCK -> revert -> repair context -> host decides what follows

Hoplon owns repository facts. The host owns workflow policy.

Connect an agent over MCP

After building Hoplon, point an MCP client at the launcher. Replace the two absolute paths with the Hoplon checkout and the repository the agent should work in:

{
  "mcpServers": {
    "hoplon": {
      "command": "node",
      "args": [
        "/absolute/path/to/hoplon/dist/bin/hoplon.js",
        "mcp",
        "serve",
        "--root",
        "/absolute/path/to/target-repository",
        "--grammars-dir",
        "/absolute/path/to/hoplon/vendor/grammars"
      ]
    }
  }
}

Use --agent-profile strict-agent when the host has completed project registration and folder-policy onboarding. The default profile remains the compatibility surface.

Use as a library

The public package name is @phalanx/hoplon; the name records the project's origin, not a runtime dependency on Phalanx.

import {
  createDefaultHoplonEngine,
  createHoplonEditSession,
} from '@phalanx/hoplon';

The engine is adapter-first. Filesystems, versioning, snapshot stores, locks, code intelligence, scanners, policy providers, vector stores, and behavior test runners are injected rather than read from ambient state.

See Integration and Host workflow for the supported entry points.

Security model

Hoplon's deterministic verdicts use manifest, path, snapshot, and AST facts. Semantic retrieval, model output, behavior tests, risk scores, and optional provider results cannot silently change structural PASS/BLOCK authority.

Hoplon is not a process sandbox. Read SECURITY.md and the threat model before granting an agent repository access.

Repository map

• src/hoplon/contracts — versioned DTOs and schemas

• src/hoplon/operations — deterministic and advisory operations

• src/hoplon/session — supervised edit state machine

• src/hoplon/adapters — environment seams and default implementations

• src/hoplon/transport, src/hoplon/mcp — remote and agent-facing surfaces

• packages — optional adapter packages

• tests — contract, flow, transport, self-hosting, and architecture proof

The current implementation truth is in ARCHITECTURE.md. The product intent is in HOPLON_VISION.md.

Contributing

Issues, design feedback, host integrations, language support, and adapter contributions are welcome. Start with CONTRIBUTING.md. Security findings belong in private vulnerability reports, not public issues.

License

Hoplon core is available under the MIT License. Optional packages declare their own licenses; in particular, the Semgrep adapter remains a separate LGPL-licensed package and is never bundled into the MIT core.