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 binary management, authentication, streaming, and lifecycle management.

Supported Agents

How Agents Work

1. Sandbox Creation

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

• Clones the target repository
• Creates a new branch for the session
• 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 Bootstrap

Sesame automatically downloads and caches agent CLI binaries at runtime — no manual installation required. Each agent has its own bootstrap logic:

Binaries are cached in the sandbox at <workDir>/.sesame/agents/<agent>/ and reused for subsequent tasks. Sesame always fetches the latest version when the cache is empty.

4. 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

5. Output Streaming

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

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

6. 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

Authentication Methods

Sesame supports two authentication approaches for agents:

API Keys

Traditional pay-per-token billing. Enter your API key in Settings → Agent Credentials → select the agent → API Key tab.

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. Go to Settings → Agent Credentials → select the agent → Subscription tab.

For Claude Code and Codex, you can authenticate in two ways:

1. Sign in directly — Click "Sign in with..." to start a browser-based OAuth flow without leaving Sesame.
2. Enter a token manually — If you already have a token from running the CLI locally, paste it below the "or enter token manually" divider.

Pros:

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

Cons:

• Tokens may expire and need refresh

See Agent Credentials for detailed setup instructions.

Credential Priority

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

1. Subscription Credentials (Agent Credentials dialog)
2. API Keys (Agent Credentials → API Key tab)
3. System API Keys (environment variables)

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

Adding Agent Support

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

• Bootstrap logic: How to download and cache the CLI binary
• 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 as fallbacks when no credentials are configured in the UI):