Coder Client

Method reference for CoderClient from the standalone @agentuity/coder package. Coder is not a ctx.* service; the client is used from agents, scripts, or external apps.

If you want practical examples before reading the full reference, see: Managing Coder Sessions with the SDK, Choosing Built-In Agents for a Coder Session, Attaching Skills to a Coder Session, Using Workspaces to Reuse Repos, Skills, and Agent Selection, Reconnecting to Existing Coder Sessions, and Creating Loop-Mode Coder Sessions.

Install

bun add @agentuity/coder

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();

Constructor

new CoderClient(options?: CoderClientOptions)

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.

getUrl()

Resolve the active Coder base URL. This returns the explicit url when you set one, otherwise it uses AGENTUITY_CODER_URL or discovery through the Agentuity API.

Returns: Promise<string>

const client = new CoderClient();
const url = await client.getUrl();
console.log(url);

Sessions

createSession(body)

Create a new coder session.

Returns: Promise<CoderCreateSessionResponse>

const session = await client.createSession({
  task: 'Implement OAuth login with GitHub provider',
  workflowMode: 'standard',
  tags: ['auth', 'feature'],
});
console.log(session.sessionId);

createAgentBuilderSession(body)

Create a dedicated agent-builder session for creating or editing custom agents.

Returns: Promise<CoderCreateSessionResponse>

getSession(sessionId)

Retrieve a session by ID.

Returns: Promise<CoderSession>

const session = await client.getSession('codesess_abc123');

updateSession(sessionId, body)

Update an existing session.

Returns: Promise<CoderUpdateSessionResponse>

await client.updateSession('codesess_abc123', {
  tags: ['auth', 'feature', 'phase-2'],
  visibility: 'organization',
});

listSessions(params?)

List sessions with optional filtering and pagination.

params fields (all optional):

Returns: Promise<CoderSessionListResponse>

const { sessions, total } = await client.listSessions({ limit: 20 });
for (const s of sessions) {
  console.log(`${s.sessionId}: ${s.label} (${s.status})`);
}

listConnectableSessions(params?)

List sessions the caller can currently connect to. Archived and history-only sessions are filtered out.

params fields (all optional):

Returns: Promise<CoderSessionListResponse>

deleteSession(sessionId)

Permanently delete a session.

Returns: Promise<void>

await client.deleteSession('codesess_abc123');

archiveSession(sessionId)

Archive an active session. Session history remains available for replay and inspection.

Returns: Promise<CoderLifecycleResponse>

await client.archiveSession('codesess_abc123');

resumeSession(sessionId)

Wake a paused sandbox session.

Returns: Promise<CoderLifecycleResponse>

await client.resumeSession('codesess_abc123');

prepareSessionForRemoteAttach(sessionId, options?)

Ensure a paused remote session is attachable before opening a controller socket. If the session is history-only, returns immediately. If the session is wakeable and the runtime is unavailable, calls resumeSession and polls getSession until the runtime is back or the timeout elapses.

Returns: Promise<CoderSession>. Returns the latest session detail, which may still be detached if the timeout elapsed.

const session = await client.prepareSessionForRemoteAttach('codesess_abc123', {
  timeoutMs: 60_000,
});
if (session.runtimeAvailable) {
  // Safe to open the controller socket
}

Session Data

getReplay(sessionId, params?)

Retrieve the data a late-joining client uses to catch up to the session's current state.

Returns: Promise<CoderSessionReplay>

const replay = await client.getReplay('codesess_abc123');

Use getReplay() when a late-joining client needs to catch up to the Hub's current state. For a structured timeline, use listEventHistory() instead.

listParticipants(sessionId, params?)

List participants for a session (primary agents, sub-agents, and observers).

Returns: Promise<CoderSessionParticipants>

const { participants } = await client.listParticipants('codesess_abc123');

listEventHistory(sessionId, params?)

List historical events for a session.

Returns: Promise<CoderSessionEventHistory>

const history = await client.listEventHistory('codesess_abc123', { limit: 50 });

Loop State

getLoopState(sessionId, params?)

Get loop-mode state for an autonomous session. Returns null loop when the session is not in loop mode.

Returns: Promise<CoderLoopStateResponse>

const { loop } = await client.getLoopState('codesess_abc123');
if (loop) {
  console.log(`Status: ${loop.status}, iteration ${loop.iteration}`);
}

The loop state includes status, iteration, maxIterations, goal, summary, nextAction, and timing fields. Status values: idle, starting, running, paused, completed, cancelled, blocked, awaiting_input.

Workspaces

Workspaces group repositories and skills into reusable configurations attachable to sessions.

createWorkspace(body)

Create a reusable workspace definition. A workspace cannot be empty: include at least one repo, saved skill, skill bucket, or agent selection.

Returns: Promise<CoderWorkspaceDetail>

const workspace = await client.createWorkspace({
  name: 'Auth System',
  description: 'OAuth and session management',
  enabledAgents: ['builder', 'reviewer'],
});

listWorkspaces()

List all available workspaces.

Returns: Promise<CoderWorkspaceListResponse>

getWorkspace(workspaceId)

Retrieve a workspace by ID.

Returns: Promise<CoderWorkspaceDetail>

deleteWorkspace(workspaceId)

Delete a workspace.

Returns: Promise<void>

Custom Agents

listCustomAgents(options?)

List custom agents in the organization library.

options fields (all optional):

Returns: Promise<CoderCustomAgentListResponse>

getCustomAgent(agentIdOrSlug)

Retrieve a custom agent by ID or slug.

Returns: Promise<CoderCustomAgent>

createCustomAgent(body)

Create a new custom-agent draft.

Returns: Promise<CoderCustomAgent>

updateCustomAgent(agentIdOrSlug, body)

Update an existing custom-agent draft. All body fields are optional; nullable fields such as description, model, and thinkingLevel can be set to null to clear them.

Returns: Promise<CoderCustomAgent>

publishCustomAgent(agentIdOrSlug)

Publish the latest draft as an immutable custom-agent version.

Returns: Promise<CoderCustomAgent>

archiveCustomAgent(agentIdOrSlug)

Archive a custom agent from the organization library.

Returns: Promise<CoderCustomAgent>

listCustomAgentVersions(agentIdOrSlug)

List published versions for a custom agent.

Returns: Promise<CoderCustomAgentVersionListResponse>

Skills

saveSkill(body)

Save a reusable skill to the caller's library.

Returns: Promise<CoderSavedSkill>

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...',
});

listSavedSkills()

List saved skills in the caller's library.

Returns: Promise<CoderSavedSkillListResponse>

deleteSavedSkill(skillId)

Delete a saved skill.

Returns: Promise<void>

createSkillBucket(body)

Group saved skills into a bucket that can be attached to sessions.

Returns: Promise<CoderSkillBucket>

listSkillBuckets()

List all skill buckets.

Returns: Promise<CoderSkillBucketListResponse>

deleteSkillBucket(bucketId)

Delete a skill bucket.

Returns: Promise<void>

GitHub

listGitHubAccounts()

List GitHub accounts available via the caller's GitHub App installations. Sign in to Agentuity before calling this method. Without an Agentuity OAuth login, the Hub returns HTTP 409 and the client throws before it can return account data.

Returns: Promise<CoderGitHubAccountListResponse>

try {
  const { connected, accounts } = await client.listGitHubAccounts();
  if (!connected) {
    console.log('Connect GitHub in the Agentuity Console first');
  } else {
    console.log(accounts.map((account) => account.accountName));
  }
} catch {
  console.log('Sign in to Agentuity first, then call listGitHubAccounts() again');
}

listGitHubRepos(accountId)

List repositories accessible under a specific GitHub account.

Returns: Promise<CoderGitHubRepositoryListResponse>

const { repositories } = await client.listGitHubRepos('12345');

Users

listUsers(params?)

List known users in the Coder Hub. Supports search and pagination.

params fields (all optional):

Returns: Promise<CoderListUsersResponse>

const { users } = await client.listUsers({ search: 'alice', limit: 10 });

Next Steps

• Coder: Concepts, session lifecycle, and workflow guidance
• @agentuity/coder Package: Install and constructor overview
• Coder CLI Commands: Full agentuity coder command reference