# How Hark works

Hark is the model-agnostic home base for every idea you're building — a hosted MCP hub that lets Claude Code, Codex, Cursor, ChatGPT and Grok share the same project memory, with venture-locked sessions, reviewable, attributed agent memory, repo-native handoff export, a pipeline from spark to shipped, and public project pages.

## Start with one project

Paste a conversation, connect a GitHub repo, or start blank. Hark suggests decisions,
the next action and blockers, each linked to the passage or commit it came from.
Nothing is filed until you accept it; where the source is silent Hark says
"Not found in the source" instead of guessing.

## Current state

One short answer to "where does this stand?": what's done, what's in progress, the
next action, and blockers. Anything a person hasn't confirmed is marked
"Not yet confirmed". Merged pull requests and releases count as observed facts.

## Decisions

Only accepted decisions appear in the list. Suggestions from imports, agents or
teammates wait for review. A new decision can replace an old one, which stays as a
one-line history.

## Hand off

Choose a recipient — developer, client or agent. Hark checks for gaps before you send.
Recipients read for free, ask questions, and add suggestions without taking a seat.
Client handoffs show only confirmed, client-facing items.

## Advanced structure (optional)

Turn on Advanced structure for a six-stage board (Vault, Recon, Blueprint,
Fabrication, Live, Cold Storage), a fuller project page, links, numbers and an
activity view.

## Built so the note gets left

- **Sessions are locked to one project** — An agent working on V-004 can't read or write V-009 without an explicit switch — and blocked attempts are logged.
- **Nothing ends without a note** — If a session goes quiet, Hark drafts the handoff from what actually happened; the next agent sees it first.
- **Agent memory is reviewable** — Decisions and state changes proposed by agents wait for your accept or reject; they never enter the brief or your public project page unreviewed.
- **The brief is short by default** — Phase, next action, last decisions, blockers, non-goals — with the full project page on request.
- **Your handoff lives in your repo too** — With export on, Hark commits .hark/HANDOFF.md, .hark/DECISIONS.md, and an AGENTS.md block, so the brief survives even if Hark is unreachable.

## Agents share one memory

Hark is a hosted MCP server at https://harkstudio.io/mcp. Connect Claude Code, Codex, Cursor,
ChatGPT, Grok, VS Code, Windsurf, Gemini CLI, or a headless script — they all read and
write the same project memory.


The session flow is three moves:

1. At session start the agent calls `get_agent_brief` (or `start_session`). The brief is
   compact by default — phase, next action, last decisions, blockers, non-goals — with
   `depth="full"` for the whole project.
2. During the session it records decisions, ships and features as they happen. Decisions and
   state changes proposed by an agent become candidates for you to accept, edit-and-accept or
   reject; unreviewed proposals never enter the brief or a public project page.
3. At the end it calls `end_session` with what it did, what changed, what's next,
   and what to watch out for. If `end_session` never runs, Hark drafts the handoff from what
   actually happened once the session goes quiet, and the next agent reads that draft first.

Other tools around the session flow: `switch_venture` (the only way to move a session to another
project), `confirm_handoff`, and `list_candidates` / `accept_candidate` / `reject_candidate`.

The one-command installer wires that session flow into a repo: a Claude Code SessionStart
hook, a stop reminder, a Cursor rule, an AGENTS.md block and a `.hark` file holding
the project code. With repo export enabled for a linked repository, Hark also commits
`.hark/HANDOFF.md`, `.hark/DECISIONS.md` and the AGENTS.md block, so the brief survives
even if Hark is unreachable.

## Sharing and publishing

Projects are private by default. Share an unlisted link with an investor or client,
or publish a public project page at `/v/<slug>` that appears in Open Studio. Guests read
only the sections you enable and can comment; they never take a seat.

## Weekly rhythm

Pick a weekly review day per workshop. At that time Hark asks one thing per active
project: confirm or replace the next action, and resolve or defer the open question.
Answers write straight back to Current state. A progress-update tool then turns your
ship and decision entries into copyable text in plain, Markdown or X-thread form.

## Links

- Pricing: https://harkstudio.io/pricing
- Connect an agent: https://harkstudio.io/how-it-works/connect
- Open Studio: https://harkstudio.io/explore
- Changelog: https://harkstudio.io/changelog