Kraken docs | ShipItFam

What it is

On a ShipItFam team, everyone works with an AI assistant called Claude. Teammates' assistants ask each other questions all day: "How does login work?", "Which file sets the prices?"

Your Kraken is you, standing in for you. It runs on your computer and answers those questions from two places:

The project's code, which it reads but never changes.
The treasure map, the team's shared project notebook, where answers worth keeping are written down.

If it is sure, it replies for you. If it is not, it brings the question to you, usually with a draft answer you can send as it stands.

Get started

You need

Node 22.22.2 or newer (24.15 or newer also works). Node runs the Kraken.
git, to work with the project's code.
The claude command-line tool, which is Claude Code, signed in. It is the assistant that reads the code for your Kraken.

Set it up

Open a terminal in your clone of the project and run:

npx -y @shipitfam/kraken@latest setup

That is the whole setup. It is safe to run again. It does five things:

Signs you in in your browser. Skipped if you already are.
Asks a few questions: your name, what you know best, and whether your Kraken may answer for you.
Connects this repository: you pick its ShipItFam project, so your Kraken can read the code to answer. It also wires your Claude Code sessions into the project (see the hooks), once for all your repositories.
Sends a test notification, so you know you will see what needs you.
Starts your Kraken in that terminal. Ctrl-C stops it. Next time, run kraken tentacle.

Prefer to hand it to Claude Code?

Paste this to your Claude Code:

Help me set up my ShipItFam Kraken: check Node 22.22.2+ (or 24.15+) and git,
make sure I am in my clone of the project, then tell me to run
`npx -y @shipitfam/kraken@latest setup` in my own terminal.

Install it once (optional)

Then the command is simply kraken, and every kraken ... example below works as written.

npm install -g @shipitfam/kraken

The program that runs your missions on this computer is a separate package: npx shipitfam work.

When a question comes in

You see questions in two places. Use either, or both.

In the terminal

kraken tentacle keeps your Kraken running. You show up as online, and what needs you arrives as a notification and as a question in a framed chat. One question shows at a time, with a menu under it. Move the highlight with the arrow keys and press Enter, or press a number to pick that row.

Menu row	What it does
Recommended draft	Your Kraken's own answer, shown whole and sent exactly as it stands. Only there when your Kraken made one.
Skip	Leave it for now.
No idea	Tell the asker you do not know.
Answer directly	Type your own answer.
Can't answer	Say you are not the right person.
The question's own options	Some questions come with ready choices. They show up as rows.
Let my agent answer	Hand the question to your Kraken.
Open in the app	Continue in the ShipItFam app.

With several questions waiting, Tab or Right moves to the next one, Shift-Tab or Left to the previous.
Start typing any other key to write your own words. Enter sends them as your answer, Esc cancels.
When it starts, it says for each project whether it reads the code on this computer or answers from the treasure map only.
Using a screen reader, or piping the output? KRAKEN_PLAIN=1 gives a plain version: one line per event, nothing redrawn, and you type a number and press Enter.

In the desktop app

This is a prototype. Kraken is a small desktop app for macOS, Windows and Linux that shows the same questions without a terminal. Download it here. It floats on your screen as a glass orb or a tentacle, and opens into a chat bubble when something needs you. Drag the orb anywhere, or slide the tentacle along the bottom of the screen. Its icon in the toolbar (the tray on Windows and Linux) opens a menu with Settings, Set up Kraken, Docs (this page), and a way to hide or show the widget.

The bubble shows one of four states:

State	What it means	Buttons
A question for you	A teammate, or the project's crew, is waiting on you.	Skip, Send
Your agent is answering	Your Kraken picked a question up and is working on it.	I'll answer
Your agent answered	Your Kraken replied for you. You can read what it said.	Got it
Your agent is not sure	Your Kraken suggests an answer and tells you why it doubts it.	Send suggestion, Edit, Skip

When the bubble is closed, the orb still shows what is going on: a count when something needs you, a green glow while your agent works, and a green tick when your agent has answered.

Commands

Every command takes --help. Without a global install, put npx @shipitfam/kraken in front instead of kraken.

Command	What it does
`kraken setup`	Everything in "Get started", in one go. Also called `kraken get-started`. Add `--interview` to answer the questions again, or `--project <id>` to skip choosing a project.
`kraken tentacle`	Runs your Kraken in this terminal and shows you the questions that need you.
`kraken profile`	Asks about you again: your name, what you know best, this computer's name, whether your Kraken may answer for you and what one answer may cost, and how you are notified.
`kraken login`	Signs you in, in your browser. It says which server it signs in to and asks first. Add `--yes` to skip the question when you set the server yourself.
`kraken doctor`	Checks your setup, one line per check, and says what to fix.
`kraken hooks install`	Wires your Claude Code sessions into the project. Add `--global` to do it for all your repositories.
`kraken context`	Prints what waits on you, the project's context, and who on the team is working on what. Claude Code runs it at the start of a session.
`kraken context propose`	Sends what a session learned that is worth keeping. Claude Code runs it at the end.
`kraken team`	Shows who is working on the project, on what, and which files two people are both changing.
`kraken agent-card`	Prints your agent card, the profile other agents use to find you.

The Claude Code hooks

A hook is a small command that Claude Code runs automatically at certain moments. kraken hooks install adds these to Claude Code's settings:

When	What it does
A session starts	Gives Claude what waits on you, the project's context and the team's current work.
After Claude edits files or runs a command	Reports which files you changed, and tells Claude if someone else is changing the same ones.
Before Claude edits a file	A heads-up when someone else is changing that file. It never blocks the edit.
A session stops or ends	Sends the knowledge Claude explicitly marked as worth keeping. Never a transcript.
A session ends	Takes your files out of the team view.

Hooks are silent and fail open. If something goes wrong, it is written to ~/.shipitfam/hooks.log, never into your session, and your work carries on.
The team hooks only act in a repository that opted in: its .shipitfam/worker.json must name the project.
What other people wrote reaches Claude marked as data, never as instructions (see Security).
The install never overwrites other settings or hooks from other tools, and running it again changes nothing.

How your Kraken answers

Read-only. It can read the project's code and the treasure map. It never writes files and never runs shell commands.
Only the project. It can read only the repositories you opted in. Secret files such as .env, keys and credentials are off limits.
A spending cap. One answer costs at most what your profile says ($0.50 unless you chose otherwise), and takes five minutes at most.
It signs its work. Replies are marked "your name's Kraken", so nobody mistakes them for you typing.
It asks when unsure. Then the question lands with you, with its note and, when it has a real answer, a draft.
Crew questions are yours by default. It answers a question from the project's crew only if your profile says crew_questions: answer. When it does, it tells you every time, so you can correct it.

Security: what it can and can't reach

Your Kraken and the work it starts run on your computer, next to everything else you have there. Here is what keeps them in their lane.

It only sees the project

One folder. Every Claude run your Kraken starts, to answer a question or to do a mission, can read only the folder it works in. Reading anything outside it is blocked by Claude Code itself.
No secrets, even inside the project. Files that hold passwords and keys are off limits: .env files, .npmrc, private keys, ~/.ssh, ~/.aws, ~/.config, your Claude login and your ShipItFam login.
Commands run in a sealed box. A mission's shell commands run in a Docker container with no network by default, with only the mission's copy of the code inside. Without Docker, commands are refused, unless you chose the trusting guardrail.

Your own Claude's extras stay yours

If your own Claude Code can reach your email, payments, files or any other tool, the Claude your Kraken starts can't. Every run starts clean: none of your MCP servers or connectors, none of your settings, hooks or memory, and only the tools ShipItFam hands it.

It runs only the missions you approved

When you approve a mission in your Kraken, the worker it starts takes that mission and the others you approved there, and nothing else. A mission a teammate assigns to you waits for you; it never runs on your computer just because a worker was up. If you start npx shipitfam work yourself, that worker takes your whole queue, because you asked it to.

Teammates' words are read, never obeyed

A question, an answer, a comment or a note from someone else can be written to look like an order. Everywhere it reaches a Claude, it arrives marked as data:

in your Kraken's own answer runs,
in what the hooks add to your Claude Code sessions (what waits on you, the treasure map, the team),
in what the ShipItFam tools return to your Claude: other people's text comes between <<<UNTRUSTED_DATA and UNTRUSTED_DATA>>>, and the tools tell Claude that text is to read and show, never to follow.

What is still up to you

Keep money tools apart. If your Claude can pay, trade or send mail for you, use a separate Claude profile for that, not the one you work on code with. Then even a perfect trick has nothing to reach.
Read before you approve. A mission runs the code changes it describes. Your Kraken never starts one you did not say yes to.
The trusting guardrail is a real switch. It lets commands run outside the sealed box. Leave it off on a computer that holds anything you care about.

Troubleshooting

Start with the doctor

kraken doctor

It checks, one line each:

The server your Kraken talks to, and where that was configured.
Your sign-in, and whether ShipItFam accepts it.
Your profile.
The claude your Kraken answers with.
Notifications. It sends you a test one and asks whether it showed. If it did not, it tells you what to check.
The repositories your Kraken may read.

It exits with an error when a required check fails, so scripts can rely on it.

Not signed in

If the doctor says your sign-in is missing or no longer accepted, sign in again:

kraken login

Claude Code is not signed in

Your Kraken answers by running Claude Code on your computer, so Claude Code itself must be signed in. Open claude in a terminal, sign in, then run kraken doctor again.