Agentuity Documentation

Start coding sessions where AI agents work in cloud sandboxes. The agentuity coder commands connect to a Coder Hub that orchestrates sessions, tools, and participants.

Global JSON Flag

All commands accept --json for machine-readable output. This is a global CLI flag, not listed per-command.

Quick Reference

Command	Description
`coder tui`	Open the interactive Coder terminal session
`coder create <task>`	Create a new session
`coder list`	List active sessions
`coder get <id>`	Show session details
`coder update <id>`	Update a session
`coder delete <id>`	Delete a session
`coder archive <id>`	Archive a session
`coder loop <id>`	Get loop-mode state
`coder replay <id>`	Get replay data
`coder participants <id>`	List session participants
`coder events <id>`	List event history
`coder users`	List known Coder users
`coder workspace`	Manage workspaces
`coder skill`	Manage saved skills

Aliases:

ls → list
show, inspect → get
new → create
rm, del, remove → delete
run, start → tui

Starting a Session

agentuity coder tui

Launches a Pi coding session connected to the Coder Hub. The CLI auto-detects the Hub URL and extension path. start and run are aliases for tui.

Options

Option	Description
`--dir <path>`	Local project directory to start from
`--url <url>`	Coder API URL override
`--extension <path>`	Coder extension path override
`--pi <path>`	Path to Pi binary override
`--agent <role>`	Agent role (e.g., `scout`, `builder`)
`--task <description>`	Initial task to execute
`--remote [session-id]`	Connect to an existing sandbox session. Paused sessions are auto-resumed. Omit the ID to browse available sessions
`--sandbox <task>`	Create a new sandbox session with the given task and attach
`--repo <url>`	Git repo URL to clone in the sandbox (used with `--sandbox`)
`--org-id <id>`	Organization ID override

Examples

# Start with auto-detection
agentuity coder tui
 
# Start as a specific agent role
agentuity coder tui --agent scout
 
# Connect to an existing sandbox session
agentuity coder tui --remote codesess_abc123
 
# Browse and select a sandbox session
agentuity coder tui --remote
 
# Create a new sandbox session with a task
agentuity coder tui --sandbox "Build an auth system"
 
# Create a sandbox with a git repo cloned
agentuity coder tui --sandbox "Build auth" --repo https://github.com/org/repo

Creating a Session

agentuity coder create "Build a REST API"

Creates a new Coder session. Pass --connect to attach immediately after creation.

Options

Option	Description
`--url <url>`	Coder API URL override
`--connect`	Connect to the session after creation
`--extension <path>`	Coder extension path override (used with `--connect`)
`--label <text>`	Human-readable session label
`--agent <role>`	Default agent role
`--visibility <level>`	`private`, `org`, or `collaborate`
`--workflow-mode <mode>`	`standard` or `loop`
`--loop-goal <text>`	Goal for loop mode
`--loop-max-iterations <n>`	Maximum loop iterations
`--loop-auto-continue`	Auto-continue without manual approval
`--loop-allow-detached`	Continue when no client is attached
`--repo <url>`	Git repo URL to clone
`--repo-branch <branch>`	Branch to checkout
`--workspace-id <id>`	Workspace to use
`--tags <list>`	Comma-separated tags
`--default-agent <slug>`	Preferred default built-in or custom agent
`--enabled-agents <list>`	Comma-separated agent slugs to include. Built-in roles like `builder` also work
`--saved-skill-ids <list>`	Comma-separated saved skill IDs
`--skill-bucket-ids <list>`	Comma-separated skill bucket IDs
`--env <pairs>`	Comma-separated `KEY=VALUE` environment variables
`--org-id <id>`	Organization ID override

Listing Sessions

agentuity coder list

Shows all active sessions on the connected Hub.

Options

Option	Description
`--url <url>`	Coder API URL override
`--org-id <id>`	Organization ID override

Output Fields

Field	Description
`sessionId`	Session identifier
`label`	Human-readable session label
`status`	Current session status
`mode`	Session mode (`sandbox` or `tui`)
`createdAt`	Creation timestamp
`taskCount`	Number of tasks
`subAgentCount`	Number of sub-agents
`observerCount`	Number of observers
`participantCount`	Total participants connected

Inspecting a Session

agentuity coder get <session-id>

Shows detailed information about a specific session, including participants, tasks, and agent activity.

Options

Option	Description
`--url <url>`	Coder API URL override
`--org-id <id>`	Organization ID override

Workspaces

Manage reusable workspace configurations from the CLI.

From the CLI, think of a workspace as a saved setup you can reuse later. It is a good fit for repository choices, dependency setup, Lead prompt guidance, and agent selection. If you want to build a workspace around saved skills or skill buckets, do that from the SDK or web app.

Do not create an empty workspace. Start with at least one repository, dependency, setup script, system prompt, or agent selection.

# List workspaces
agentuity coder workspace list
 
# Create a repo-backed workspace
agentuity coder workspace create "Auth System" --repo https://github.com/org/repo
 
# Create a workspace with agent selection
agentuity coder workspace create "Review Workspace" --enabled-agents builder
 
# Create a workspace with setup inputs
agentuity coder workspace create "Node Workspace" --dependency git --setup-script-file ./setup.sh
 
# Create a workspace with Lead prompt guidance
agentuity coder workspace create "Focused Review" --system-prompt-file ./WORKSPACE_PROMPT.md --system-prompt-mode append
 
# Show workspace details
agentuity coder workspace get ws_abc123
 
# Delete a workspace
agentuity coder workspace delete ws_abc123

Workspace Create Options

Option	Description
`--url <url>`	Coder API URL override
`--description <text>`	Workspace description
`--scope <scope>`	`user` or `org`
`--repo <url>`	Git repository URL to store on the workspace
`--repo-branch <branch>`	Branch to associate with the repository
`--dependency <list>`	Comma-separated APT dependencies to install while preparing the workspace
`--setup-script <script>`	Inline shell script to run while preparing the workspace
`--setup-script-file <path>`	Read the setup script from a file
`--system-prompt <text>`	Inline Lead system prompt to apply to sessions created from the workspace
`--system-prompt-file <path>`	Read the Lead system prompt from a file
`--system-prompt-mode <mode>`	`append` or `overwrite`
`--enabled-agents <list>`	Comma-separated agent slugs. Built-in roles like `builder` also work
`--org-id <id>`	Organization ID override

Skills

Manage saved skills and skill buckets in your library.

# List saved skills
agentuity coder skill list
 
# Save a skill
agentuity coder skill save --repo my-org/skills --skill-id code-review --name "Code Review"
 
# Create a custom SKILL.md-backed skill
agentuity coder skill create --skill-id release-checklist --name "Release checklist" --content-file ./SKILL.md
 
# List skill buckets
agentuity coder skill buckets
 
# Create a skill bucket
agentuity coder skill buckets --create "Frontend Skills" --description "Reusable UI skills"
 
# Delete a skill
agentuity coder skill delete skill_abc123
 
# Delete a skill bucket
agentuity coder skill buckets --delete bucket_abc123

Skill Create Options

Option	Description
`--url <url>`	Coder API URL override
`--skill-id <id>`	Skill identifier
`--name <text>`	Skill name
`--description <text>`	Skill description
`--content <text>`	Inline `SKILL.md` content
`--content-file <path>`	Read `SKILL.md` content from a file

URL Resolution

Coder commands resolve the Hub URL in this order:

--url
AGENTUITY_CODER_URL
Hub discovery through the authenticated Agentuity API

Authentication comes from your normal CLI login session or the standard CLI auth environment variables.

Next Steps

Coder Service: Overview and SDK usage with @agentuity/coder
Claude Code Plugin: AI-assisted development from Claude Code
Sandbox Commands: Manage sandbox environments directly