Agents

Sesame supports multiple AI coding agents through a unified abstraction layer. Each agent runs as a CLI tool inside a sandbox, with Sesame handling authentication, streaming, and lifecycle management.

Supported Agents

How Agents Work

1. Sandbox Creation

When a task starts, Sesame creates an isolated sandbox environment:

• Clones the target repository
• Creates a new branch for the task
• Sets up the working directory

2. Credential Injection

Sesame injects authentication credentials based on the agent type:

• API Keys: Set as environment variables
• Subscription Tokens: Written to agent-specific credential files
• GitHub PAT: Available for repository operations

3. Agent Execution

The agent CLI is spawned as a subprocess with:

• The user's prompt as input
• Access to the cloned repository
• Streaming output captured in real-time

4. Output Streaming

Agent output streams to the browser via Server-Sent Events (SSE):

• Terminal output (commands, responses)
• File changes
• Error messages
• Progress updates

5. Completion

When the agent finishes:

• Changes are committed to the branch
• Branch is pushed to the remote
• Pull request created (if configured)
• Sandbox cleaned up (unless "Keep Alive" enabled)

Authentication Methods

Sesame supports two authentication approaches for agents:

API Keys

Traditional pay-per-token billing. Enter your API key in Settings → API Keys.

Pros:

• Simple setup
• Works immediately
• Clear cost tracking

Cons:

• Pay-per-token can be expensive for heavy use

Subscription Credentials

Use your existing AI subscriptions (Claude Max, ChatGPT Pro, Copilot) instead of API billing.

Pros:

• Flat monthly rate
• May be more cost-effective for heavy use
• Use subscriptions you already pay for

Cons:

• More complex setup (OAuth tokens)
• Tokens may expire and need refresh

See Credentials for detailed setup instructions.

Credential Priority

When running a task, Sesame checks for credentials in this order:

1. User's Subscription Credentials (Agent Credentials dialog)
2. User's API Keys (Settings → API Keys)
3. System API Keys (environment variables)

If no credentials are found, the task fails with an authentication error.

Adding Agent Support

Sesame's agent system is extensible. Each agent is defined in packages/agents/ with:

• Spawn logic: How to start the CLI
• Credential injection: Where to put auth tokens
• Output parsing: How to interpret the agent's output

See the Development Guide for details on adding new agents.

Environment Variables

System-wide API keys (used when users don't have their own):