goal-engine
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@goal-engine set a goal: all unit tests pass and lint is clean"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
goal-engine
Run-until-done /goal loops for every major agentic CLI — Claude Code, Codex CLI, OpenCode, Cursor, and any MCP-compatible agent.
You state a completion condition ("all tests pass", "the PR is ready"); the agent keeps working across turns until an external evaluator confirms the condition is verifiably met — or until a loop guard or turn budget stops a runaway session.
Architecture: three composable layers
┌─────────────────────────────────────────────────────────┐
│ Layer 3 — npm package + installer CLI │
│ npx -y goal-engine · goal-engine install --all │
├─────────────────────────────────────────────────────────┤
│ Layer 2 — MCP server (goal-engine) │
│ set_goal / check_goal / get_status / clear_goal │
│ Evaluator via MCP sampling (no external API key) │
│ SQLite state · loop guard · turn budget │
├─────────────────────────────────────────────────────────┤
│ Layer 1 — portable SKILL.md │
│ Works standalone on any Agent Skills runtime │
└─────────────────────────────────────────────────────────┘Each layer works on its own. The skill alone gives you self-checked goal loops anywhere; adding the MCP server upgrades the self-check to an independent evaluator with persistent state.
Related MCP server: agent-runtime-mcp
Why an external evaluator?
A skill-only goal loop asks the model to grade its own work inside the same context window — a confused agent can convince itself the goal is met. The MCP spec's sampling primitive lets this server request a completion from the connected client's own model in a fresh context, with a strict evaluation prompt. No API key, no extra provider, CLI-agnostic.
Evaluator fallback chain (strongest available wins):
MCP sampling — the client's model judges the transcript (zero config)
Anthropic API — set
ANTHROPIC_API_KEY(model:claude-opus-4-8, override withGOAL_ENGINE_EVAL_MODEL)OpenAI API — set
OPENAI_API_KEY(model:gpt-4o, override withGOAL_ENGINE_OPENAI_MODEL)Self-check — the tool returns strict self-verification instructions and never auto-completes
A flaky evaluator can never end a goal early: every evaluator failure resolves to done: false.
Install
# Install the /goal skill into every detected agent CLI
npx -y goal-engine install --all
# Or a specific one
npx -y goal-engine install --to claude-code # also: codex, opencode, cursorThen connect the MCP server:
Claude Code
claude mcp add goal-engine -- npx -y goal-engineCodex CLI (~/.codex/config.toml)
[mcp_servers.goal-engine]
command = "npx"
args = ["-y", "goal-engine"]OpenCode (~/.config/opencode/config.json)
{ "mcp": { "goal-engine": { "type": "local", "command": ["npx", "-y", "goal-engine"] } } }Bun users can substitute bunx goal-engine everywhere — the server auto-selects bun:sqlite, node:sqlite, or a JSON file for state.
Usage
/goal all unit tests pass and lint is cleanThe agent then:
calls
set_goalwith the condition verbatim,works toward it with all available tools,
calls
check_goalat the end of every turn with a concrete work summary,treats each
done: falsereason as its next instruction,stops only on
done: true(or escalates onloop_detected/budget_exhausted).
MCP tools
Tool | Input | Output |
|
|
|
|
|
|
|
|
|
|
|
|
Safety rails built into check_goal:
Loop guard — 3 identical consecutive summaries return
loop_detectedand tell the agent to change approach or ask the user.Turn budget —
max_turns(default 40, max 500) returnsbudget_exhaustedwith a partial-progress instruction.Strict parsing — unparseable evaluator verdicts resolve to
done: false.
Optional: Claude Code Stop hook
The MCP-tool flow relies on the agent calling check_goal. The Stop hook closes the gap: it fires whenever Claude tries to stop, and blocks the stop while a goal is active and unmet.
mkdir -p ~/.goal-engine
cp hooks/stop-goal-evaluator.sh ~/.goal-engine/
chmod +x ~/.goal-engine/stop-goal-evaluator.sh~/.claude/settings.json:
{
"hooks": {
"Stop": [{ "hooks": [{ "type": "command", "command": "~/.goal-engine/stop-goal-evaluator.sh" }] }]
}
}Notes:
The hook honors
stop_hook_active(no infinite recursion) and lets the agent stop once the turn budget is exhausted.Claude Code caps consecutive Stop-hook blocks at 8 by default; set
CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=40to match the default turn budget.With
ANTHROPIC_API_KEYset, the hook evaluates the transcript's last assistant message; without it, the block reason instructs the agent to self-verify and finish viaclear_goal completed=true.
Environment
Variable | Default | Purpose |
|
| State file path |
|
| Data directory |
| — | Evaluator fallback when MCP sampling is unavailable |
|
| Anthropic evaluator model |
| — | Second evaluator fallback |
|
| OpenAI evaluator model |
Development
bun install
bun run typecheck # tsc --noEmit
bun test # unit + MCP integration tests (in-memory transport)
bun run build # tsc → dist/
bun run smoke # drives dist/index.js over stdio with raw JSON-RPCProject layout:
SKILL.md Layer 1 — portable Agent Skill
src/index.ts CLI entry: serve (default) | install | check-hook
src/server.ts MCP server: the four goal tools + sampling wiring
src/evaluator.ts Evaluator chain: sampling → Anthropic → OpenAI → self-check
src/db.ts State: bun:sqlite | node:sqlite | JSON fallback
src/loop-guard.ts Identical-turn loop detection
src/hook.ts Claude Code Stop hook logic
src/installer.ts Cross-CLI skill installer
hooks/stop-goal-evaluator.sh Stop hook wrapper script
agents/openai.yaml Codex plugin metadataLicense
MIT
Available Tools
4 toolscheck_goalCheck goalA
Evaluate whether the active goal is fully met. Call at the end of every turn with a concrete summary of the work just done. Returns done=true when finished, or done=false plus the specific gap to address next.
Inputs: session_id (required), summary (required).
clear_goalClear goalA
End a goal session. Pass completed=true when the goal was verifiably met (used by the self-check fallback); otherwise the session is abandoned.
Inputs: session_id (required), completed.
get_statusGet goal statusA
Inspect the current goal session: condition, turn count, elapsed time, and last evaluation.
Inputs: session_id.
set_goalSet goalA
Start a run-until-done goal loop. Records the completion condition; the agent should then work toward it and call check_goal at the end of every turn until the goal is met.
Inputs: goal (required), session_id, max_turns.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: set_goal starts, check_goal evaluates, clear_goal ends, and get_status inspects. No overlap or confusion.
All tools follow a consistent verb_noun pattern with underscores (set_goal, check_goal, clear_goal, get_status), making them predictable.
Four tools are exactly right for a goal engine's core lifecycle: start, evaluate, end, and inspect. No unnecessary extras or missing essentials.
The set covers the full lifecycle of a goal session: set, check, clear (with success/failure), and status. No obvious gaps for the intended functionality.
Related MCP Connectors
Durable, user-controlled goals for AI agents, kept across any MCP client.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Goal-based task manager for humans and AI. Read goals, add subtasks, report results.
Shared task layer for AI agents: tasks, handoffs and decisions that persist across tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides state and log management tools designed for long-lived AI agents that may be interrupted and resumed. It enables tracking agent progress and maintaining an append-only event history to ensure continuity across multiple sessions.4MIT
- FlicenseNot gradedqualityDmaintenanceEnables persistent task and goal management with AI-powered decomposition, cross-session continuity, and fault-tolerant multi-agent pipelines.1-
- AlicenseBqualityCmaintenancePersistent brain, memory, loop controller, and reminder engine for AI coding agents.4219 npmMIT
- AlicenseAqualityDmaintenanceProvides AI agents with a lightweight task-management and self-verification layer to define goals, track checkpoints, detect scope drift, and verify completion against explicit done criteria.12MIT