# Connect Hark — Working with agents [Features: Work with any agent](https://harkstudio.io/features#work-with-any-agent) ## 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. One command: ``` 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. [Features: Repo export (.hark/)](https://harkstudio.io/features#repo-export-hark) > 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 ~/.codex/config.toml: ``` [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. 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 Repo CLAUDE.md: ``` ## 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//brief. ## Verify it works Ask your client: "List my Hark workspaces." Expected: your workspace names. Then: "Create a project called Connection test in ." 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.