Coder

Agentuity Coder is the session layer around coding agents. It runs coding agents in cloud sandboxes, gives each run a durable Hub, and lets humans, apps, and other agents attach to the same stream from the SDK, API, CLI/TUI, or web app.

Use Coder when coding work needs to survive the terminal that started it: start a session from an app or internal tool, inspect it later, resume it after a disconnect, or let teammates watch the same session.

When to Use Coder

Use Coder when the unit of work is a shared session with history, lifecycle, and reconnect semantics, not just a sandbox process.

Managing Sessions

How It Works

A Coder session has three components:

1. Hub: Real-time broadcast server where participants (humans, apps, agents) subscribe to the same event stream; also manages session lifecycle and tools
2. Agent: An AI coding agent that connects to the Hub and executes tasks
3. Sandbox: An isolated cloud environment where the agent writes, builds, and tests code

Sessions support multiple participants: the primary agent, sub-agents that split work, teammates in the web app, a terminal TUI, SDK/API clients, and observers that stream the session in real time.

Agents and Skills

Coder has a few different layers that are easy to mix up:

• Built-in agents are the built-in Coder team roles like builder, reviewer, and scout
• System skills are Hub-managed skills that the platform injects automatically
• Saved skills and skill buckets are user-managed selections you attach to sessions or workspaces

Use enabledAgents to choose the agent roster for a session or workspace. Use defaultAgent when you want routed work to prefer a specific agent.

Workspaces bundle the setup a coding session needs: repositories, saved skills, skill buckets, and agent selections. Custom agents let you package reusable domain knowledge, tools, service access, and companion agents. Use createAgentBuilderSession() when you want Agent Builder to help create or update a reusable custom agent programmatically.

Reading Session State

When you inspect a session from the SDK or CLI, these fields do most of the work:

In practice:

• historyOnly: true usually means “switch to replay or a read-only session view”
• runtimeAvailable: true usually means “the session is live enough to attach to”
• wakeAvailable: true usually means “the session is not live now, but it may still be resumable”
• fresh sessions often have little or no replay, event history, or participant data yet

Which Read Method to Use

SDK Usage

Install the standalone package:

bun add @agentuity/coder

If you want the cleanest first SDK integration, start with Managing Coder Sessions with the SDK. For the rest of the runnable Coder examples, see the Coder cookbook section, including how to branch into Loop-Mode Sessions, Attach Skills, Use Workspaces, and more.

Creating and Listing Sessions

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();
 
// Create a new session
const session = await client.createSession({
  task: 'Implement OAuth login with GitHub provider',
  workflowMode: 'standard',
  tags: ['auth', 'feature'],
});
console.log(`Session created: ${session.sessionId}`);
 
// List active sessions
const { sessions } = await client.listSessions({ limit: 10 });
for (const s of sessions) {
  console.log(`${s.sessionId}: ${s.label} (${s.status})`);
}

Session Operations

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();
 
// Get session details
const session = await client.getSession('codesess_abc123');
 
// Update a session
await client.updateSession('codesess_abc123', {
  tags: ['auth', 'feature', 'phase-2'],
  visibility: 'organization',
});
 
// Archive a completed session so its history stays available for replay and inspection
await client.archiveSession('codesess_abc123');
 
// Resume a paused session (wakes the sandbox)
await client.resumeSession('codesess_abc123');
 
// Permanently delete a session
await client.deleteSession('codesess_abc123');

Session Data and Replay

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();
const sessionId = 'codesess_abc123';
 
// Get the replay payload a late-joining client uses to catch up
const replay = await client.getReplay(sessionId);
 
// List participants in a session
const participants = await client.listParticipants(sessionId);
 
// Get event history
const events = await client.listEventHistory(sessionId, { limit: 50 });
 
// Check loop state (for autonomous sessions)
const loopState = await client.getLoopState(sessionId);

Workspaces and Skills

Workspaces group repositories, skills, and agent selections into reusable configurations that can be attached to sessions.

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();
 
// Create a workspace
const workspace = await client.createWorkspace({
  name: 'Auth System',
  description: 'OAuth and session management',
  enabledAgents: ['builder', 'reviewer'],
});
 
// Save a reusable skill
const skill = await client.saveSkill({
  repo: 'my-org/my-skills',
  skillId: 'code-review',
  name: 'code-review',
  description: 'Review code for security issues',
  content: 'Review the changes for OWASP top 10 vulnerabilities...',
});
 
// List saved skills
const { skills } = await client.listSavedSkills();

Client Configuration

The client picks one of two modes based on what you provide.

Discovery mode (recommended). Omit url and AGENTUITY_CODER_URL; the client calls the Agentuity API to resolve your org's Hub. region is only consulted in this mode.

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient({
  apiKey: 'agentuity_sk_...',           // Override AGENTUITY_SDK_KEY
  region: 'usc',                        // Region used when discovering the Hub
  orgId: 'org_...',                     // Organization scope
});

Explicit mode. Set url (or AGENTUITY_CODER_URL) to a known Hub. Discovery is skipped, and region has no effect.

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient({
  url: 'https://coder.example.com',     // Explicit Hub URL, skips discovery
  apiKey: 'agentuity_sk_...',
  orgId: 'org_...',
});

The client resolves the Hub URL in this order:

1. options.url (explicit)
2. AGENTUITY_CODER_URL environment variable
3. Auto-discovery via the Agentuity API

Most apps only need the API key. Set AGENTUITY_SDK_KEY and let the client discover the rest.

CLI Usage

# Open the interactive terminal session
agentuity coder tui
 
# Create a managed session without attaching
agentuity coder create "Build an auth system"
 
# Create a managed session and attach immediately
agentuity coder create "Build an auth system" --connect
 
# Open the interactive terminal session against an existing remote session
agentuity coder tui --remote codesess_abc123
 
# List active sessions
agentuity coder list
 
# Inspect a session
agentuity coder get codesess_abc123

See Coder CLI Commands for the full command reference.

Session Modes

Running agentuity coder tui with no extra flags launches the interactive terminal session. Using agentuity coder tui --sandbox <task> creates a cloud sandbox session and attaches to it. Using agentuity coder tui --remote <session_id> attaches to an existing connectable session, and bare --remote opens the session picker.

Session Lifecycle

status is a detailed string from the Coder service. For UI grouping, use the SDK's bucket field.

Connecting via Plugins

The Claude Code and OpenCode plugins integrate with the Coder ecosystem:

• Claude Code/Cowork: The Agentuity plugin adds auto-activated Agentuity skills to Claude Code and Cowork. Use it when you want help deploying apps, managing cloud services, or building with the SDK from that editor workflow. It is not the API for creating or inspecting Coder sessions.
• OpenCode: The OpenCode plugin adds Agentuity-aware agents, slash commands, and dashboard tooling to OpenCode. Use it when you want an editor-based multi-agent workflow rather than a managed Coder session.

Next Steps

• Managing Coder Sessions with the SDK: Core SDK flow for create, read, archive, and delete operations
• Choosing Built-In Agents for a Coder Session: Choose the built-in roster for a session
• Attaching Skills to a Coder Session: Attach saved skills and skill buckets from your library
• CoderClient Reference: Full method reference for @agentuity/coder
• Coder CLI Commands: Full command reference