# Goal

> Persistent objectives for Claude Code. A /goal plugin with auto-continuation, audit-gated completion, MCP server with push channel, and headless drive.

- **Type:** MCP server
- **Install:** `agentstack add mcp-pyyush-goal`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pyyush](https://agentstack.voostack.com/s/pyyush)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [pyyush](https://github.com/pyyush)
- **Source:** https://github.com/pyyush/goal

## Install

```sh
agentstack add mcp-pyyush-goal
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# goal

`goal` is a durable objective layer for developer agents. It turns a high-level coding outcome into local state, task checkpoints, statusline visibility, and an evidence gate before model-side completion can be claimed.

Use Claude Code's built-in `/goal` for a single-session task. Use this plugin when the work needs to survive `/clear`, compaction, restarts, rate limits, or handoff between Claude Code and Codex.

## Why It Exists

Long coding runs fail in predictable ways: the objective drifts, status gets buried in the transcript, a restart loses context, or the model claims a finish before checking the actual files. `goal` makes those failure modes explicit and inspectable.

- File-backed state: every active goal lives under `.goal/goals/.json`.
- Session ownership: multiple Claude Code windows can work in one repo without sharing a mutable record accidentally.
- Task checkpoints: `goalframe` turns the raw ask into a compact, auditable work plan.
- Evidence discipline: `overclaim` blocks unsupported "done" claims.
- Local control: `goalctl`, MCP tools, hooks, statusline, HTTP, and cowork relay all operate on the same state.

## Install

This installs the slash command, hooks, statusline integration, MCP server wiring, and local CLI helpers.

```bash
git clone  ~/goal
cd ~/goal
./bin/goal-setup --non-interactive
```

Restart Claude Code after install so the command, hooks, statusline, and MCP server register.

Useful checks:

```bash
./bin/goal-setup --dry-run
goal-statusline-install --audit
goalctl --help
```

Manual install is still available:

```bash
./install.sh user
```

Rollback is scope-local: remove or disable this plugin in the Claude scope where it was installed, or delete the generated hook/statusline/MCP entries from that scope's Claude settings. Existing `.goal/` records are ordinary project files.

## 60-Second Quickstart

Start a durable objective:

```text
/goal:goal Refactor the auth module to use the new session API; keep tests green
```

Inspect and steer it:

```text
/goal:goal status
/goal:goal tasks
/goal:goal next
/goal:goal steer "prefer focused tests before broad cleanup"
```

Control the same goal from a terminal:

```bash
goalctl status
goalctl tasks
goalctl next
goalctl pause
goalctl resume
goalctl clear
```

In Claude Code versions where the command picker exposes this plugin as bare `/goal`, that alias is equivalent. The explicit `/goal:goal` form avoids ambiguity with the native command.

## Core Loop

1. The user gives a developer outcome, not a chat instruction.
2. `goalframe` shapes it into outcome, verification, constraints, boundaries, and task checkpoints.
3. Runtime state is written under `.goal/` with atomic writes and per-goal locks.
4. Hooks, MCP tools, and `goalctl` keep the same record moving.
5. `overclaim` audits the evidence before model-side completion is recorded.

## Companion Skills

The custom skills are the product logic around the loop.

`goalframe` runs at intake. It converts a vague or oversized objective into a compact spec:

```json
{
  "title": "Migrate auth sessions",
  "outcome": "auth uses the new session API",
  "verification": "auth tests and smoke flow pass",
  "constraints": "public exports stay stable",
  "tasks": ["map call sites", "migrate core flow", "verify edge cases"]
}
```

`overclaim` runs at exit and before progress claims. It classifies each claim by support level:

| Level | Meaning |
|---|---|
| `confirmed` | Directly checked this turn against files, commands, tests, or artifacts. |
| `partial` | Some named part is still unverified or incomplete. |
| `proxy-only` | Related evidence exists, but it does not prove the claim. |
| `blocked` | The required evidence cannot be gathered yet. |

The result is a goal system that treats "done" as an evidence-backed state, not a guess.

## Cowork Relay

Cowork is opt-in. Add `.goal/cowork.yml`, start a peer bridge, and Claude Code and Codex can continue the same objective through handoff envelopes. The supported Claude Code ↔ Codex path is verified by local relay tests and the account-backed live E2E.

```bash
goalctl cowork init
goalctl bridge start codex --root /path/to/project
```

When a runner hits a rate limit or server error, the bridge can write `.goal/handoff/NNNN.md`, move the goal to `relaying`, and let the peer pick up from the shared state. If every configured provider is throttled, the goal queues until headroom returns.

See [docs/cowork.md](docs/cowork.md) for the full protocol.

## Developer Interfaces

`goalctl` is the headless control surface:

```bash
goalctl create "Ship the migration" --budget 50000
goalctl --json status
goalctl audit
goalctl listen --grep goal.completed
goalctl serve-http --port 7474
```

The loopback HTTP shim binds `127.0.0.1` only:

```bash
curl -X POST http://127.0.0.1:7474/goal \
  -H 'Content-Type: application/json' \
  -d '{"objective":"Ship the migration","token_budget":50000}'
```

The MCP server exposes model-side tools for goal creation, state reads, completion, task progress, lane leases, handoffs, queued messages, and steering. See [mcp/README.md](mcp/README.md).

## Reliability Model

- Objectives are treated as untrusted data.
- Atomic writes use temp files and `rename(2)`.
- Per-goal locks serialize hooks, MCP, CLI, and bridge writes.
- `.goal/pause` is a hard local kill switch.
- Model-side completion is audit-gated; terminal `goalctl mark-achieved` is explicit caller-owned control.
- The HTTP shim is loopback-only.
- Runtime records live under `.goal/` and are ignored by default.

## Requirements

- macOS or Linux (Windows via WSL)
- `bash` 3.2+, `jq`, `uuidgen`
- Node 18+ for MCP, HTTP, telemetry, and bridge helpers

## Docs

- [Cowork protocol](docs/cowork.md)
- [MCP server](mcp/README.md)
- [Goal record schema](docs/schema/state.v2.json)
- [Generated README assets](docs/assets/README.md)

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pyyush](https://github.com/pyyush)
- **Source:** [pyyush/goal](https://github.com/pyyush/goal)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pyyush-goal
- Seller: https://agentstack.voostack.com/s/pyyush
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.