Sensei CLI.

Integrate Kosuke puts the CLI, the MCP server and one prompt to paste into your agent on one page.

Install

npm install -g @kosuke-ai/kosuke
kosuke --version

Sign in

1. Create an API key in Settings > You > API keys. See Authentication.
2. Run kosuke auth login and paste the key when it asks. What you type stays hidden.
3. Sensei checks the key and saves it. It prints a line such as Logged in to https://app.kosuke.ai; member of 2 workspaces. API key saved to /home/you/.config/kosuke/credentials.json.

kosuke auth status get shows where the key comes from and whether Sensei accepts it. kosuke auth logout deletes the stored key.

In CI or any script that runs without a person, skip the login. Set the KOSUKE_API_KEY environment variable to the key, or pass --api-key <token> to any command. A key from a flag or the environment wins over the stored one.

Inside a chat sandbox, where the credential is a sandbox agent token, the tree narrows to the operations that token may call. The same holds in a Cron Run, where the credential is the run's own key. The tools of the connected integrations, the workspace's and, in your own turns, yours, are there too: see Run integration tools.

The MCP server does not need this key: your agent's client signs you in through the browser instead, though it also accepts an API key as a bearer token.

Your first commands

# 1. Find the project's id.
kosuke projects list --json | jq '.data[] | {id, name}'

# 2. File a task, note its task id, then start it.
kosuke tasks create <orgId> --hint-project <projectId> \
  --title "Fix footer typo" --description "Fix the typo in the pricing page footer"
kosuke tasks start <orgId> <taskId> --project-id <projectId> --skill ship

# 3. Follow the turn until it ends, printing what the agent says.
kosuke sessions jobs watch <projectId> <sessionId> <jobId> \
  | jq -r 'select(.type == "message") | .data.text'

tasks create saves Todo work. tasks start starts its execution. The older sessions create --status backlog remains supported.

How commands work

• Ids are positional arguments, in the order the help shows, such as kosuke sessions get <projectId> <sessionId>. A command that takes a project id and then a session id also runs with the session id alone, or with --session-id <id>: kosuke sessions get <sessionId> looks the project up first. A command whose session id is a flag, such as kosuke sensei sessions facts get, also takes it as its first positional argument.
• Request fields are flags, such as --title, --content or --exclude-archived.
• --body '<json>' sends a whole request as JSON. --body-file <path> reads it from a file, and --body-file - reads it from stdin. A few commands, such as projects env-vars create, take only a whole body.
• --attach <path> attaches a file. Repeat it for several files. sessions create, sessions send, sessions prompt update, sessions queue update, deploys start, deploys queue update and files set take files. files set takes one file of up to 25 MB, the others up to 10 MB each.
• Every API command that returns a body prints JSON to stdout, with the result under data; one whose request answers 204 prints nothing. In a terminal the JSON is indented. Piped into another program or a file, it is compact: one line, with each row of a data list on its own line. --pretty prints it indented anyway. Errors go to stderr, and the command exits with 1.
• --json, or KOSUKE_OUTPUT=json in the environment, asks for the platform's whole JSON. Pass it in any script that reads the output with jq.
• The lists are short without it: projects list, sessions list, tasks list, crons list, activity list, sensei threads list, sensei cards list and files list print at most 20 rows, each with the fields you pick a row by, and a last line on stderr such as 20 of 3122. More: --cursor <c>. --all reads every page, --full keeps every field, and --fields picks from whole rows.
• --fields id,title,chatSession.id prints only those fields, per row of a list, or of the list the answer holds (such as the crons of crons list), else of the object. A dot reaches into a nested object. A field no row has exits with 1 and names the closest fields. --format compact prints a header line, then one tab-separated line per row, with nulls empty and times to the second; what sits beside the rows, such as the next cursor, goes to stderr. --fields also works with --json.
• Times in the JSON are ISO 8601 in UTC, for scripts to parse. user usage get and workspaces usage breakdown get count calendar days in your own timezone unless you pass --tz. When your timezone cannot be read they count UTC days and say so on stderr.
• --repository takes owner/repo, such as --repository acme/storefront, or the JSON {"owner":"acme","name":"storefront"}.
• --help works at every level. kosuke sessions --help lists the group's commands, and kosuke sessions send --help lists that command's flags, one line each. --help --long prints each description in full.
• kosuke help --compact lists every command you can run with its arguments, one line per group, in about 4,000 characters. An agent reads it once in place of many --help calls.
• An unknown command or flag names the closest one: a mistyped lst after kosuke sessions qa runs answers Did you mean ...? with the commands of that group.

Find a session

kosuke find <query> finds sessions in one call. The query is a pull request number such as 3323 or #3323, a session id, a task id, or words of a title such as "compact view". It prints one line per match, with the workspace, project, session, your Sensei Thread that follows it, its task, its pull request number and the head commit Sensei last saw.

kosuke find 3323
kosuke find "compact view" --json | jq -r '.data[] | "\(.projectName) \(.sessionId) #\(.pullRequestNumber)"'

It searches what kosuke sessions list shows you: every workspace you belong to, or the token's own workspace inside an agent's turn.

Command reference

Tasks

The tables list the main commands, not every one. kosuke help --compact lists every command, and kosuke <group> --help every command in a group.

auth

projects

Only a workspace admin changes a project's setup, services and environment, in the web or desktop app. The CLI signs in with an API key, so the commands marked 403 above, and deploys start, get 403 SETTINGS_ADMIN_ONLY for every member, admins included, until API keys get a project settings scope. Reads still work. See What only the web app can do.

An import with a first task looks like this. The task starts on /kosuke:ship when the first deploy lands.

kosuke projects create --org-id <workspaceId> --name storefront \
  --repository-url https://github.com/acme/storefront \
  --prompt "add a footer"

A repository from kosuke-starter starts from a sentence. See Preview and publish. While Start from kosuke-starter is off on the deployment, --description is refused with 403 KOSUKE_STARTER_OFF and makes no repository.

kosuke projects create --org-id <workspaceId> --description "A booking page for my yoga classes"

sessions

deploy

preview

files

A workspace's shared Files. A path is folder names and a file name joined by / from the workspace root, such as prototypes/board/a-columns.html.

Each command prints the item's url, which opens it in Files. A sandbox, a Cron Run and Sensei can list, read, write and move. Their instructions tell them not to delete, though their credentials reach files delete. A folder Sensei keeps and a locked file refuse every caller. A Quick Question from Spotlight can list and read only. A key reaches only the workspaces its owner belongs to.

kosuke files set <workspaceId> --path notes/plan.md --text "# Plan"
kosuke files set <workspaceId> --path designs/home.png --attach ./home.png
kosuke files list <workspaceId> --folder designs

user files

Your personal Files, which belong to you and to no workspace. Only you see them. They take the same paths, flags and limits as a workspace's files commands, with no workspace argument.

An agent reaches the personal Files of the member it acts as: Sensei, a chat session agent in a Turn that member sent, a Cron Run of their Personal Cron, and the Slack agent answering them. An agent acting as the workspace is refused. A Connected App's Connector Token reaches them as your API key does.

kosuke files set personal --path notes/ideas.md --text "# Ideas"

crons

workspaces

user

integrations

sensei

github, models, activity and agent

Run integration tools

kosuke integrations lists, describes and runs the tools of the connected integrations. kosuke integrations list is an overview: one block per toolkit with the scope, label, account, short id and alias of each connection, and how many read and write tools the toolkit has. The kosuke agent summary get digest lists the same connections. Add --toolkit <slug> to see a toolkit's tools, tools get <name> for a tool's schema, and call <name> --args '<json>' to run it. A list that is cut short says how many of how many it shows. call exits 0 when the tool ran, 1 when the tool or the platform reported an error (a write whose outcome is unknown says not to retry), and 2 when the command itself was used wrongly, such as an API key without --workspace. The hidden kosuke integrations tools list and kosuke integrations tools call print the raw JSON of the same two routes.

When a toolkit has several connections, pick one with --account: its alias such as notion-personal, its short id or full id, or scope:label such as personal:Engineering. Case, curly quotes and extra spaces do not matter. A bare personal or workspace works when exactly one connection of that scope can run the tool. A missing or ambiguous account is refused with the choices, one per line with its alias, and every call prints the connection it ran on (alias, scope, label and account) on stderr, beside the tool's text on stdout.

Inside a chat sandbox, a Cron Run or a Sensei turn, the turn's credential decides what you reach, as in Who can use a connection. Sensei with no workspace named uses your personal integrations and the Personal space’s workspace integrations. Naming a workspace uses that workspace’s integrations plus your personal ones, never the Personal space’s. Personal Crons use the Personal space’s integrations plus yours; Workspace Crons and Deploy Chat use workspace integrations only. Restricted integrations need a grant for the call’s workspace, Personal included.

From your laptop with an API key:

• list and tools get need --workspace <workspaceId>. You must belong to that workspace. They show its connections and your own personal ones. With no shared workspace, name your Personal space’s id; the flag is still required.
• call runs your own personal connections only. A call on a workspace connection is refused: workspace connections run only inside an agent's turn.
• A Connector Token from the MCP server is refused for all three.

kosuke integrations list --workspace <workspaceId>
kosuke integrations list --workspace <workspaceId> --toolkit gmail
kosuke integrations call notion_search_notion_page --workspace <workspaceId> --account notion-personal --args '{"query":"roadmap"}'

Follow a turn with sessions jobs watch

kosuke sessions jobs watch follows one turn as it runs, so a script does not have to poll. The job id is the chatJobId that sessions create and sessions send print when they start a turn. A send that waits Up next prints a queuedMessageId instead. Each event is one JSON line on stdout. Messages meant for a person go to stderr.

If the connection drops, watch reconnects and picks up where it left off. When the turn ends, a last watch.links line carries the session, preview and pull request links. If some events could not be read, a watch.status line says "complete": false.

Use it with your coding agent

The MCP server covers most of what a coding agent needs. A few things only the CLI does:

• Attach a file, with --attach.
• Print every event of a turn as it happens, with kosuke sessions jobs watch.
• Read your own Sensei Chat, with kosuke sensei chat get.

Give your agent a digest

kosuke agent summary get prints a digest of about 1,500 tokens for an agent to read. Its first line gives the time in your own timezone, named, such as 2026-11-05 09:12 Europe/Rome. When your timezone cannot be read it gives UTC and says so. It lists:

• the chat sessions that need you
• your connected Subscriptions and their usage across every released provider, and with --workspace that workspace's AI providers too
• with --workspace (inside an agent's turn, its own workspace), the connected integrations, one line each: toolkit, alias, scope, label and account. A long list ends with "and N more", and a refused or failed read says so rather than leaving the section out
• your oldest New Activity events, one line each
• the workspaces it read

It marks seen only the events it prints. The rest stay New for kosuke activity list --unseen. Add --workspace <id> to cover one workspace, or --peek to mark nothing seen.

To have your coding agent start from it, paste this line into your AGENTS.md or CLAUDE.md:

Before you answer anything about my Sensei work, run `kosuke agent summary get --peek` and read what it prints.

Configuration

A flag wins over its environment variable, and both win over the stored key. The stored key is credentials.json in the config folder, readable only by you.

Update

Run the install command again, then check the version:

npm install -g @kosuke-ai/kosuke
kosuke --version

Next steps

• Connect your coding agent
• Ship a change end to end
• Follow a turn

Use kosuke sensei threads close <threadId> to mark a thread Done. Open cards, running replies and messages waiting Up next prevent it. Threads have three states: Needs you, Working and Done; event lines and Receipts do not make them unread.