MCP server · 11 stacks

Your coding agent, checked by your own test suite.

HexaCore Agent gives Claude Code, Cursor and any MCP client your project's rules, real test runs, a checkpoint before every write, and lessons learned from every failure it fixes.

$ npx -y hexacore-agent

Compiled and tested in CI for all 11 stacks Never edits your tests Local files only

Set up your client How it learns npm

~/shop · claude

› add refunds to the orders service
● resume_session go · 4 slices · 6 lessons
How this user works: shows the plan first (observed)
● execute_scaffolding refunds · dryRun → 6 files
● execute_scaffolding refunds → checkpoint cp_7f3a
● run_quality_assurance test ✗ 2 failing
refunds/service_test.go:41 assignment to entry in nil map
↳ lesson go-nil-map-init helped 5 of 6 times
● run_quality_assurance test ✓ 38 passed
credited go-nil-map-init evidence: diff
● check_architecture 0 errors · 0 warnings

Install

One line in the client you already use.

Node 20 or newer. HexaCore Agent reads the workspace from your client's MCP roots, so there is nothing else to configure.

Run in your terminal:

claude mcp add hexacore-agent -- npx -y hexacore-agent

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "hexacore-agent": {
      "command": "npx",
      "args": ["-y", "hexacore-agent"]
    }
  }
}

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "hexacore-agent": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "hexacore-agent"]
    }
  }
}

Add to claude_desktop_config.json (Settings → Developer → Edit config):

{
  "mcpServers": {
    "hexacore-agent": {
      "command": "npx",
      "args": ["-y", "hexacore-agent"],
      "env": { "HEXACORE_WORKSPACE": "/path/to/your/project" }
    }
  }
}

Also listed in the MCP Registry as io.github.rbaezc/hexacore-agent. From source: clone the repo, npm install && npm run build, and point your client at node dist/cli/mcp_launcher.js.

Vertical slices

One feature, one folder, wired and tested.

HexaCore Agent scaffolds each feature as a vertical slice that follows your project's layout and naming. This is the Go slice from the session above, planned with dryRun before a single file is written.

$ hexacore scaffold go refunds --dryRun

internal/slices/refunds/
  domain.go        entities and rules
  service.go       use cases
  repository.go    port + adapter
  handler.go       HTTP entry point
  module.go        composition root
  service_test.go  tests first

domain

Depends on nothing outside the slice. The architecture audit fails if it imports an outer layer.

ports

Interfaces the slice needs, with adapters behind them, so tests swap real storage for fakes.

module

The only place where the slice is wired. Other slices use its public API, never its internals.

tests

Generated with the slice and run with your stack's own runner. They are the specification.

The loop

It learns from what your tests prove, not from what the model claims.

Every check that goes from red to green becomes evidence. A lesson earns credit only when the actual fix matches it.

1 red
A check fails

Your stack's own runner reports file, line and test. HexaCore Agent snapshots the project and offers lessons that match the failure.
2 fix
The agent fixes it

Every write goes through a checkpoint. A patch that makes things worse is rolled back, and tests are never edited.
3 green
The diff is the evidence

The green project is compared with the red snapshot. A lesson whose terms show up in the changed lines gets the credit.
4 lesson
Proven lessons travel

After 3 helps at 70% or better, a lesson becomes a Claude Code skill and joins your library in ~/.hexacore for your other projects.

↺ The next failure starts at step 1 with better lessons. Unused ones fade after 60 days, duplicates get merged.

20 tools

Everything an agent needs between "add refunds" and a green build.

Understand

Start each session where the last one ended.

resume_session: Plans, decisions, QA history, your preferences and the best lessons.
search_knowledge_base: Rule search in English and Spanish over conventions, project rules and ADRs.
check_architecture: Whole-repo audit: slice coupling, layer direction, file size.

Design

Decide before writing.

define_contract: Contract-first API for a slice.
record_decision: An ADR with the trade-offs, indexed for search.

Build

Slices that fit the host project.

execute_scaffolding: Ports, adapters, composition root and tests. Preview with dryRun.
orchestrate_task: Rules, scaffold, audit and tests in one plan, with auto-fix.
resume_plan: Continue an interrupted plan from its last step.

Verify and undo

Real toolchains, exact rollback.

run_quality_assurance: Build, typecheck, lint and test with structured failures.
list_checkpoints: Every write HexaCore Agent made, newest first.
rollback_changes: All-or-nothing return to any checkpoint.

Learn

Lessons scored by evidence.

record_lesson: Turn a red-to-green episode into a lesson.
rate_lesson: Explicit feedback on whether a lesson helped.
review_lessons: Effective, weak, stale and duplicate lessons.
merge_lessons: Fold duplicates into one, keeping their evidence.
export_skills: Write proven lessons as Claude Code skills.
share_lessons: Copy proven lessons to your library for other projects.

Remember you

Each session starts adapted.

remember_preference: "Always show the plan first", for you or for one project.
forget_preference: Remove one preference, the observed habits, or everything.
record_handoff: Notes for the next session or the next person.

Guided prompts for your client's slash menu: /design_feature, /implement_slice and /fix_failing_checks. Every rule document and the session briefing are also exposed as MCP resources.

Stacks

Generated code has to pass the real toolchain.

CI scaffolds two slices into a minimal project for each stack and runs its own compiler and tests on every change.

Node.jstsc + vitest

Reacttsc + vitest

React Nativejest

.NETdotnet test

Laravelphpunit

Rustcargo test

Pythonpytest

Gogo test

Flutterflutter test

Rubyrspec

Elixirmix test

Your rules.hexagen/rules/*.md

Guardrails

Safe to leave running in your repo.

Writes you can undo

Every change goes through a checkpoint in .hexagen/checkpoints/, and rollback restores files exactly, or not at all.

Tests are the spec

Auto-fix patches implementation code only. A patch that leaves more failures than before is rolled back.

Small files

No generated or edited file may pass 250 lines. The slice linter and the architecture audit both enforce it.

Plain files you can commit

Plans, ADRs and QA history live in .hexagen/state.json. Lessons are markdown in .hexagen/skills/ you can review in a PR.

A profile you control

Preferences and observed habits stay in ~/.hexacore/profile.json. Text that looks like a credential is refused.

No corrupted state

State is written to a temporary file and renamed atomically. Toolchain processes run with timeouts behind a circuit breaker.

CLI

The same agent, from your terminal and CI.

Ships in the same package. JSON on stdout, and exit code 2 when checks are not green, so it drops into any pipeline.

# install once, or prefix each command with npx -p hexacore-agent
npm install -g hexacore-agent

# rule search, in English or Spanish
hexacore rag "reglas de capas en go"

# preview a slice, then write it
hexacore scaffold rust payments --dryRun --workspace ../shop
hexacore scaffold rust payments --workspace ../shop

# checks and the architecture audit (warnings fail with --strict)
hexacore qa rust --checks typecheck,test --workspace ../shop
hexacore arch --strict --workspace ../shop

# what it has learned, and undo
hexacore lessons --workspace ../shop
hexacore rollback cp_7f3a --workspace ../shop

FAQ

Questions people ask first.

Does it need an API key or its own model?

No. HexaCore Agent runs on your machine as an MCP server and your client's model does the thinking. For auto-fix it asks that same model through MCP sampling, when the client supports it. Otherwise the client fixes the code and runs the checks again.

What happens when a test fails?

You get structured failures: test, file, line and message, plus any lessons that match. With sampling, HexaCore Agent requests a search-and-replace fix to implementation code, applies it through a checkpoint, re-runs the checks, and rolls it back if things got worse.

How do I continue tomorrow, or after a crash?

Your client calls resume_session at the start. It reads .hexagen/state.json and returns a briefing: unfinished plans (continue them with resume_plan), failing checks, recent ADRs, the last handoff note, your preferences and the most useful lessons.

Does it adapt to me?

Yes. When you state a lasting preference, the model saves it with remember_preference. HexaCore Agent also notices habits from how you use it: your stacks, the checks you run, whether you preview scaffolding, how often you roll back. Both open every briefing, and forget_preference removes them. HEXACORE_PROFILE=off turns the user profile off.

Can I use it in an existing project?

Yes. It detects the stack and the existing layout, and new slices follow your folders and naming. Add your own conventions as markdown in .hexagen/rules/ and your ADRs in docs/adr/; both are searched next to the bundled rules.