Use Korium with Claude Code and Cowork

Connect Claude Cowork

Use a remote custom connector through your Claude account. In Customize → Connectors, choose “+” and “Add custom connector,” then enter https://api.kyroco.ai/mcp. Add it, complete Korium’s browser sign-in and enable it for the conversation.

For a managed Claude organization, an owner adds the connector in Organization settings → Connectors. Members then connect and authenticate individually. Confirm that you signed in to the intended Korium workspace.

Cowork’s remote connection runs through Anthropic’s servers. A local claude_desktop_config.json entry is a different mechanism and is not the Cowork setup. Use Anthropic’s custom connector guide if the controls differ.

In a fresh Cowork task, ask it to call agent_search. Then complete the first-memory exercise and check the capture receipt and returned source. Seeing the connector in a list is not the complete test.

Give Cowork a useful piece of work

Start with a document or transcript you are allowed to share. Ask Cowork to compare it with what was already agreed, rather than simply summarizing it. This example is a task recipe, not a claim that every transcript is saved automatically:

Read these meeting notes and search Korium for the earlier
project decisions they refer to.
Prepare a follow-up with three sections: agreed changes,
open questions and proposed actions. Cite the sources.
Show me the memories you recommend saving before you write them.
Do not treat a suggestion as a decision or invent an approval.
After my review, save the approved changes and show the receipts.

Check the final memories from another fresh task connected to the same workspace. Local files, Claude’s own conversation memory and Korium are different places; a document being present does not prove the decision was captured.

The shell hooks and .claude/settings.json examples below are for Claude Code. Do not paste them into Cowork expecting the same lifecycle events. Start Cowork with the task rule above and verify the actual read/write calls.

1. Connect Claude Code and sign in

Run this in the project where you want to use Korium:

claude mcp add --transport http korium https://api.kyroco.ai/mcp
claude mcp list

Start Claude Code and open /mcp. Select Korium and authenticate if requested. Complete the browser flow and return to Claude Code.

Connection scope determines whether this setup applies to one project or more broadly; choose that deliberately if you share configuration. See Anthropic’s MCP guide. Do not commit access tokens to .mcp.json or paste credentials into the command.

2. Prove memory works

Follow the first-memory exercise. Confirm a successful capture, open a fresh conversation and search for it. You should see the saved decision, not just an answer based on the current conversation.

The connected tool names may include a client-specific prefix. Use the tools ending in agent_capture and agent_search, or use the exact names the client shows you.

3. Add the project instructions

Merge the Korium memory rule into CLAUDE.md. Tell Claude which scope represents the project, what evidence to keep and how to handle a failed connection. Preserve the instructions already there.

For reusable skills, read the Korium toolkit manifest and review the relevant files before adding them to .claude/skills/. Skills explain a way of working; they do not grant permissions or run themselves.

4. Add the hooks you want

Save the session-start reminder in .claude/hooks/ and read it first.

The Stop hook that keeps the code index current comes from the Mac CLI itself. Run korium-cli hooks install in the repository: it installs the Git hook and prints the Stop entry below. If the repository has no Korium hook yet, your first korium-cli index from a terminal offers to do this for you.

Merge these entries into .claude/settings.json. Keep your existing settings and other hook entries. Omit Stop if you aren’t using the code index.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$(git rev-parse --show-toplevel)/.claude/hooks/korium-session-start.sh\"",
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "korium-cli index --allow-removals --no-wait --from-hook || [ $? -eq 3 ] || exit 1"
          }
        ]
      }
    ]
  }
}

The SessionStart command resolves the repository root before loading the script. Review the configuration in /hooks; the current event contract is in Anthropic’s hook reference.

What the Stop hook indexes

At the end of each Claude turn, the Stop hook indexes the working tree as it is, uncommitted edits included, under the branch the checkout is on. It updates only that branch’s index and never replaces another branch’s. A detached checkout is turned down.

When this Mac is not signed in, korium-cli exits with status 3 right away, without indexing. It also opens a sign-in in your browser and indexes once you finish, unless a sign-in is already open, you turned one down in the last hour, or there is no screen to show it on. The [ $? -eq 3 ] part lets the hook end quietly in that case instead of reporting an error after every turn, so leave the end of the command as it is. Any other failure still ends with exit 1, so Claude Code shows it to you.

If you set up the task-end script from an earlier version of this guide, replace its Stop entry with the one above: that script indexes only the branch named in its korium.publishBranch setting, which korium-cli itself does not read. Replace a Stop entry pasted from an earlier korium-cli release too. An entry without --from-hook waits for a browser sign-in when this Mac is not signed in.

When the code index is behind

When Claude searches code with code_locate and this checkout’s index is missing or behind, the answer says so and names the fix: run korium-cli index in the checkout, which indexes the branch the checkout is on. The answer carries this in its next_step field as well as in its warning. Korium also says it in the instructions it sends when Claude Code connects, so Claude can update the index itself and search again, naming the branch.

Give the sample researcher only the tools it needs

The toolkit’s Claude Code researcher reads local source and can search and capture Korium memory. It is not a memory-read-only agent. A connection named korium normally exposes these allowlist entries:

tools: Read, Glob, Grep, mcp__korium__agent_search, mcp__korium__agent_capture

Inspect the actual names in your client before copying the agent file into .claude/agents/. Adjust the two MCP entries if the connection is named differently. Read / Glob / Grep alone would exclude the memory calls; granting every MCP tool would give more access than this example needs.

For a strictly read-only reviewer, remove capture from both its allowlist and its instructions, and use read-only server authorization. See Claude Code’s tool permissions.

Why the Stop hook does not block

Claude Code reads a Stop hook’s exit status 2 as an instruction to continue working, and korium-cli exits 2 when Korium refuses an index. An ordinary indexing refusal must not keep asking the agent to finish the same task forever, so the entry ends in || exit 1: any failure becomes exit 1, you see the message, and the turn ends normally. The next turn or commit tries again.

The hook never waits for a sign-in. If this Mac is not signed in, it opens the Korium sign-in in your browser in the background and returns at once; the index is updated when you finish signing in. --no-wait returns once Korium has accepted the upload, so an exit of 0 does not prove the new index is searchable yet. Updating the code index is not a memory capture: decisions still need the MCP capture tool.

If you add your own memory-capture reminder, block once and verify a successful capture receipt. Do not treat the mere presence of a tool call as success.

5. Check the complete workflow

Start a new session, ask for a relevant Korium search and complete a harmless task. Confirm the task-end hook ran. After the index has published, a code search should identify the expected branch and commit.

If a hook is silent, inspect which project settings loaded, whether the session-start script exists at the resolved path, and whether korium-cli is on the PATH Claude Code uses. Test the script separately with sample JSON before changing authentication. If the connection fails, use /mcp for MCP and korium-cli status for the Mac CLI.