Working with agents in Hark: reviews, trust and keys

How agents should use the tools

Tool descriptions say only what each tool does. This is the working guidance agents also receive from the onboard prompt.

• start_session: Call this first, before any work.
• start_session: Pair it with end_session when you stop — otherwise Hark auto-drafts a handoff from your activity after 45 minutes of inactivity.
• get_agent_brief: Call this at the start of every session before doing work.
• get_agent_brief: Request depth='full' only when you need the whole project (AI context doc, session handoffs, all decisions, features, checklist, sparks).
• onboard: Use this (or start_session) as the very first call of a session.
• get_venture: Call this first to load context before editing.
• create_venture: ALWAYS ask the user first which workshop it belongs in, or whether to create a new workshop for it.
• propose_venture_from_project: Use this once, after reading a codebase or project, to hand Hark everything in ONE call.
• propose_venture_from_project: Afterwards, ask the user for one constraint or decision that only Hark should know and record it with add_journal_entry. Do not call create_venture first — this replaces it.
• add_journal_entry, add_feature, move_feature_status, toggle_checklist_item: Use during a session as decisions are made and work completes — do not batch everything into the AI context doc (CLAUDE.md).
• toggle_checklist_item: Use list_checklist first if the label is unknown.
• move_stage: Set them with update_build_state first.
• capture_spark: Use create_venture or promote_spark to graduate it.
• delete_venture: Prefer archive_venture for reversible shelving.
• search_ventures: Use this FIRST when the user says 'find my ideas about X' or before forking/creating something related — then call get_venture_context to pull the actual projects.
• get_venture_context: Intended flow: search_ventures → get_venture_context → build on the results in a new or forked project.
• list_workspace_repos: Use before connect_venture_repo to find the exact full_name (owner/repo).
• end_session: Call this at the end of every session, before you stop.
• close_session: Prefer end_session when you actually did work; use this when you need to unstick a connection or stop without a handoff.
• update_claude_md: Edit the file in the repo instead. This doc is for stable conventions; living state belongs in update_build_state, the journal and features.
• accept_candidate: Any earlier decision this may replace comes back as suggested_supersedes for you to confirm with supersede_decision.
• supersede_decision: Call it only after the user said yes in this chat, with explicit ids.
• list_workspaces, list_ventures: Use the id (or slug) as workspace_id in other tools when you belong to more than one workshop.
• add_journal_entry (supersedes): Never guess — only pass ids you were told about or read from list_journal_entries.

How much agents can approve on their own

Each project has a trust level, set by a workshop owner or admin in the project's settings. It controls what an agent's proposals can become without a person clicking Accept. Decisions are never approved automatically, at any level, and there is no mode that changes that.

• Standard (default): you review every agent proposal. Repo facts backed by a commit, PR or release are accepted as observed.
• Relaxed: also auto-accepts the Current state lists (In progress, Next up, Blockers, Open questions) and handoff drafts inferred from repo activity. Decisions, non-goals, summary and phase are still reviewed.
• Autopilot: auto-accepts everything an agent proposes except decisions, non-goals and phase changes. It is armed per project and per agent tool, switches itself off after 24 hours (re-arm from the project page), shows a banner while it is on, and is never available workshop-wide.
• At every level, anything that conflicts with an accepted decision is never auto-accepted. It goes to review with the conflict shown.
• Anything accepted this way is labelled "Auto-approved" in the review list, the agent brief and every handoff view, including what recipients see, so it is never confused with a person's approval.
• To batch the rest, use "Accept all from this session" on a session card or in the daily digest email. It takes every quoted and observed item from that session and leaves decisions, non-goals and phase changes as a short list for you.

Install the session setup in your repo

Run this inside the repo you're building. It writes a Claude Code SessionStart hook that pulls the brief in for you, a stop hook that drafts the handoff when a session ends, a Cursor rule plus Cursor stop hooks (same behavior), an AGENTS.md block for Codex, and a .hark file holding the project code.

curl -fsSL https://harkstudio.io/install.sh | sh -s -- V-012

Swap V-012 for your project code. Leave it off and it reads .hark, or asks. Optional: export HARK_PAT=… (create one on your profile) and the SessionStart hook fetches the live brief itself instead of just telling the agent to.

• .hark — the project this repo belongs to.
• .claude/hooks/hark-session-start.sh + .claude/settings.json — the brief, injected on every session start.
• .claude/hooks/hark-session-end.sh — the handoff reminder on stop.
• .cursor/rules/hark.mdc — the same session flow, always on, in Cursor.
• AGENTS.md — the block Codex and most other agents read.

If you also turn on repo export for a linked repository (Venture → Repository → Export handoff to repo), Hark commits the brief itself into the same repo: .hark/HANDOFF.md with the Current state and latest session handoff, .hark/DECISIONS.md with your accepted decisions, and the AGENTS.md block. Only accepted content is written, only inside the markers, and unchanged files are skipped — so the brief still reads even if Hark is unreachable.

It never overwrites an existing .claude/settings.json — the hook wiring lands in .claude/settings.hark.json for you to merge. Read the script first if you'd rather not pipe it: harkstudio.io/install.sh

Codex config

[mcp_servers.hark]
url = "https://harkstudio.io/mcp"

Codex picks up the installed AGENTS.md block automatically, so the session flow travels with the repo.

Three layers, one read

Stable context lives in your repo. Living state lives in Hark. The brief is injected at the start of every session, so whichever agent shows up starts where the last one stopped.

• Stable context — CLAUDE.md (the AI context doc): conventions, stack, house rules. Rarely changes. Can be synced straight from your repo.
• Living state — the Current state card, the journal (ship / decisions / sessions), features and the checklist. Changes every session.
• The agent brief — one call that composes both layers into an ordered, context-sized read.

Rule of thumb: if it will still be true in three months, it belongs in CLAUDE.md. If it describes where the build is right now, it belongs in Hark's living state.

The session flow

1. get_agent_brief (or start_session) — read the brief before touching anything. It is compact by default: phase, next action, last decisions, blockers, non-goals. Pass depth="full" when you need the whole project.
2. Work with the tools as you go: add_journal_entry for decisions, move_feature_status as features complete, toggle_checklist_item for the project page checklist, update_build_state when the picture shifts, create_handoff to make a handoff link for a developer, client or agent. Decisions and state changes an agent proposes arrive as candidates for you to review.
3. end_session — writes the handoff (What I did / What changed / What's next / Watch out for), updates the Current state, and — if repo export is on — commits the brief to your repository.
4. close_session — stops the session without writing a handoff. Use it if an agent gets stuck on the wrong project: it always works, whatever state the session is in, and leaves the next call free to start fresh.

What happens if end_session never runs

Sessions that go quiet don't just vanish. After the session has been idle for a while, Hark drafts the handoff itself from what actually happened during it — the decisions logged, the features moved, the state changed — and marks it as a draft. The next agent reads that draft first. The venture's Current state card shows the last brief read and last handoff with the client and time, and flags "session without handoff" when a brief was read more than six hours ago with no end_session after it, with an instruction you can paste to your agent.

Guardrails you don't have to configure

• Sessions are locked to one venture. An agent working on V-004 can't read or write V-009 without calling switch_venture, and blocked attempts are logged and counted in workspace settings.
• Agent memory is reviewable. Decisions and Current state changes proposed by an agent become candidates — they never enter the brief or your public project page until you accept, edit-and-accept, or reject them.
• The brief stays short so it survives a small context window; depth="full" is there when you need everything.
• With repo export on, the same brief lands in your repository as .hark/HANDOFF.md, .hark/DECISIONS.md and an AGENTS.md block.

The tools around the session flow

• switch_venture — move the session to a different venture on purpose. Without it, cross-venture reads and writes are refused.
• confirm_handoff — have the incoming agent confirm it read the handoff, which is what marks a handoff as picked up.
• list_candidates — everything an agent has proposed and you haven't reviewed yet.
• accept_candidate / reject_candidate — accept (optionally with edits) or reject a proposed decision or state change. Only accepted content reaches the brief, the public project page and the repo export.

Claude Code

## Current state lives in Hark

This project's Current state lives in Hark (venture V-###).

- At session start: call get_agent_brief with project "V-###" and follow it.
- During the session: log decisions with add_journal_entry, move features with move_feature_status.
- At session end: call end_session with what you did, what changed, what's next, and what to watch out for.

Or ask directly: "Start a Hark session on V-012, then implement the next item in next_up."

Codex

Codex reads the same tools. Open with: "Call the Hark onboard prompt for V-012 and summarise the brief before you write code." Finish with: "Call end_session on V-012."

Session entries are private to the workshop — they never appear on public project pages. The brief is also available as a resource at hark://ventures/<code>/brief.

Verify it works

Ask your client: "List my Hark workspaces." Expected: your workspace names.

Then: "Create a project called Connection test in <workspace>." Expected: a new V-### appears in the app and the activity log shows the source ("via Claude Code", "via Codex", etc.). Delete the test venture afterward.

Troubleshooting

• "Unauthorized request origin" — the client origin isn't allowlisted; retry from the latest app version, or email hello@harkstudio.io.
• Consent screen loops / stale token — remove the connector in the client, sign out of Hark, sign back in, re-add the connector.
• Tools list is empty — the connector isn't enabled for this chat (Claude and ChatGPT require enabling it per conversation).
• Plan cap error — you've hit the monthly agent-call cap for this workspace; see billing.
• Old endpoint — anything pointing at a lovable.app URL must be updated to harkstudio.io/mcp.