Subsystem Search

subroutine agent

The 1 command under subroutine agent, each with its arguments and options.

subroutine agent [OPTIONS] COMMAND [ARGS]...

Set an AI agent up as a principal of its own.

subroutine agent create

subroutine agent create [OPTIONS] [name]

Give an agent an identity of its own, and say how to hand it over.

Examples:

subroutine agent create web --workspace acme --here

subroutine agent create claude --profile worker --project WEB

subroutine agent create sam --profile collaborator --project SR --write SUBSAMPLE

subroutine agent create reporter --profile observer --expires now+30d

subroutine agent create subsample --workspace projects --project SUBSAMPLE

This is 'user create', 'user add' and 'token create' as one act, because they are one decision: an account with no membership authenticates and can do nothing, which reads as a broken token rather than as a missing role.

Handing the token over is half the work. An agent that can run shell commands reaches this instance two ways - through the tools its editor wired up, and by running 'subroutine' itself - and those resolve credentials separately. Give the token only to the editor and the agent is itself over the tools and *you* in its shell, which is worse than plainly acting as you: half its work is correctly attributed, so a spot check finds its name and concludes the setup worked.

'--here' covers both halves for one project, where the 'subroutine' plugin runs the tools. Run it in the directory Claude Code is opened in: it writes the credential into that directory's .claude/settings.local.json, under this connection's variable, makes the repository ignore that file, and prints nothing secret - so an agent can run it for you without ever seeing the credential. A session started there afterwards acts as the agent - in its tools too where they reach this connection, and a plugin naming none reaches this machine's default. Under 'subroutine-remote' it covers the shell only: that plugin's tools present its one token in every project, until the directory is switched to the 'subroutine' plugin, which it says how to do.

'--store' covers both halves for every agent on this machine instead. It records the credential beside yours rather than in place of it, and 'subroutine' then acts as the agent in a process the agent started and as you everywhere else - including in 'git' hooks, which are the highest-volume writer here.

'--profile' says what the agent is *for*, and expands into the flags below it. 'worker' owns one project; 'collaborator' reads several and writes one of them; 'observer' reports and changes nothing. A combination that means two things at once is refused rather than resolved - '--profile observer --write WEB' is not a narrower observer.

The credential is checked by being presented, not by being described: what it can actually do is read back from the instance before this command claims anything.

It says whom the agent answers to, which is whoever ran it. When that is another agent, it prints the one command that hands the new one to the person that agent answers to, which only a person may run.

Arguments

Options