Commands & directives

This page documents Takopi’s user-visible command surface: message directives, in-chat commands, and the CLI.

Message directives

Takopi parses the first non-empty line of a message for a directive prefix.

Directive	Example	Effect
/engine	/codex fix flaky test	Select an engine for this message.
/project	/happy-gadgets add escape-pod	Select a project alias.
@branch	@feat/happy-camera rewind to checkpoint	Run in a worktree for the branch.
Combined	/happy-gadgets @feat/flower-pin observe unseen	Project + branch.

Notes:

• Directives are only parsed at the start of the first non-empty line.
• Parsing stops at the first non-directive token.
• If a reply contains a ctx: line, Takopi ignores new directives and uses the reply context.

See Context resolution for the full rules.

Context footer (ctx:)

When a run has project context, Takopi appends a footer line rendered as inline code:

• With branch: `ctx: <project> @<branch>`
• Without branch: `ctx: <project>`

This line is parsed from replies and takes precedence over new directives.

Telegram in-chat commands

Command	Description
/cancel	Reply to the progress message to stop the current run.
/agent	Show/set the default agent for the current scope.
/file put <path>	Upload a document into the repo/worktree (requires file transfer enabled).
/file get <path>	Fetch a file or directory back into Telegram.
/topic <project> @branch	Create/bind a topic (topics enabled).
/ctx	Show topic context binding (topics enabled).
/ctx set <project> @branch	Update topic context binding.
/ctx clear	Remove topic context binding.
/new	Clear stored sessions for the current scope (topic/chat).

CLI

Takopi’s CLI is an auto-router by default; engine subcommands override the default engine.

Commands

Command	Description
takopi	Start Takopi (runs onboarding if setup/config is missing and you’re in a TTY).
takopi <engine>	Run with a specific engine (e.g. takopi codex).
takopi init <alias>	Register the current repo as a project.
takopi chat-id	Capture the current chat id.
takopi chat-id --project <alias>	Save the captured chat id to a project.
takopi plugins	List discovered plugins without loading them.
takopi plugins --load	Load each plugin to validate types and surface import errors.

Common flags

Flag	Description
--onboard	Force the interactive setup wizard before starting.
--transport <id>	Override the configured transport backend id.
--debug	Write debug logs to debug.log.
--final-notify/--no-final-notify	Send the final response as a new message vs an edit.