### Manual Testing: Fresh Install and Daemon Start

Source: https://github.com/preset-io/agor/blob/main/context/archives/database-migrations.md

Steps for manually testing a fresh installation of Agor, including initializing the project, starting the daemon, and verifying that migrations have run and tables were created.

```bash
# 1. Test fresh install
rm -rf ~/.agor/agor.db
agor init
agor daemon start
# Verify: migrations ran, tables created
```

--------------------------------

### Local Development Setup - Agor

Source: https://github.com/preset-io/agor/blob/main/README.md

Instructions for starting the Agor daemon and UI locally using pnpm. Assumes a multi-terminal setup.

```bash
# Terminal 1: Daemon
cd apps/agor-daemon && pnpm dev  # :3030

# Terminal 2: UI
cd apps/agor-ui && pnpm dev      # :5173
```

--------------------------------

### Install and Test Agor Live (npm)

Source: https://github.com/preset-io/agor/blob/main/TEST_PLAN.md

Installs the latest 'agor-live' npm package globally, initializes the project configuration (skipping if already initialized), lists the current configuration, and lists existing users. This helps verify the basic functionality of the published package.

```bash
npm install -g agor-live@latest
agor init --skip-if-exists
agor config list
agor user list
```

--------------------------------

### Example Environment Configuration (YAML)

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/guide/concepts.mdx

This YAML configuration defines commands to start and stop an environment, along with a template for application URLs. It utilizes environment variables and arithmetic expressions to dynamically assign ports based on the worktree's unique ID.

```yaml
up_command: "UI_PORT={{add 9000 worktree.unique_id}} pnpm dev"
down_command: "pkill -f 'vite.*{{add 9000 worktree.unique_id}}'"
app_url_template: "http://localhost:{{add 9000 worktree.unique_id}}"
```

--------------------------------

### Install and Run OpenCode Server

Source: https://github.com/preset-io/agor/blob/main/context/projects/opencode.md

Commands to install the OpenCode CLI globally and start a local OpenCode server. This is essential for development and testing of the OpenCode integration.

```bash
npm install -g opencode-ai
opencode auth login
opencode serve --port 4096
```

--------------------------------

### OpenCode Server Setup and Agor Daemon Startup (Bash)

Source: https://github.com/preset-io/agor/blob/main/context/archives/opencode-integration.md

Provides the necessary bash commands to set up and run the OpenCode server and the Agor daemon. This involves starting the Go-based OpenCode server on a specific port and then running the Agor daemon and UI.

```bash
# Terminal 1: Start OpenCode server (leave running)
opencode serve --port 4096

# Terminal 2: Agor daemon
cd apps/agor-daemon && pnpm dev

# Terminal 3: Agor UI
cd apps/agor-ui && pnpm dev

```

--------------------------------

### Set Up Local Development with pnpm

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/guide/development.mdx

This sequence sets up a local development environment for Agor using pnpm. It involves cloning the repository, navigating into the directory, and installing dependencies. This method is recommended for working on environment management features or when avoiding Docker-in-Docker complexity.

```bash
git clone https://github.com/preset-io/agor
cd agor
pnpm install
```

--------------------------------

### Set Up Local Development Environment for Agor

Source: https://github.com/preset-io/agor/blob/main/TEST_PLAN.md

Provides commands to set up the local development environment for the Agor project. It involves installing dependencies, and then starting the Agor daemon and UI in separate terminals (or concurrently using a root command). This is crucial for local testing and development.

```bash
cd /Users/max/code/agor
pnpm install
cd apps/agor-daemon && pnpm dev  # Terminal 1
cd apps/agor-ui && pnpm dev      # Terminal 2 (or pnpm dev from root)
```

--------------------------------

### Clone and Run Agor with Docker Compose

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/guide/development.mdx

This command sequence clones the Agor repository, navigates into the directory, and starts the development environment using Docker Compose. It provides instructions for accessing the UI and lists the pros and cons of using Docker for development.

```bash
git clone https://github.com/preset-io/agor
cd agor
docker compose up
# Visit http://localhost:5173 → Login: admin@agor.live / admin
```

--------------------------------

### Run Agor Project with Docker Compose

Source: https://github.com/preset-io/agor/blob/main/TEST_PLAN.md

Executes the command to start all services defined in the Docker Compose configuration for the Agor project. This is used to test the containerized environment, including installation, migrations, and service startup.

```bash
cd /Users/max/code/agor
docker compose up
```

--------------------------------

### Build and Run Tasks with Turbo

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/guide/development.mdx

This section provides examples of using Turbo, a build system, for task orchestration within the Agor monorepo. Commands like `pnpm build`, `pnpm typecheck`, and `pnpm dev` leverage Turbo to run tasks efficiently in parallel and manage dependencies.

```bash
# Build all packages in dependency order
pnpm build

# Run typecheck across all packages in parallel
pnpm typecheck

# Run dev servers (daemon + UI)
pnpm dev
```

--------------------------------

### Install code-server on macOS, Linux, and via npm

Source: https://github.com/preset-io/agor/blob/main/context/explorations/ide-integration.md

Provides commands for installing code-server using Homebrew on macOS, a shell script for Linux, and npm for global installation. Includes a command to verify the installation by checking the version.

```bash
brew install code-server
```

```bash
curl -fsSL https://code-server.dev/install.sh | sh
```

```bash
npm install -g code-server
```

```bash
code-server --version
# Output: 4.105.1
```

--------------------------------

### YAML Environment Configuration Template

Source: https://github.com/preset-io/agor/blob/main/context/concepts/core.md

Example configuration for setting up runtime environments in Agor. It defines commands for starting and stopping services, and templates for health check and application URLs, utilizing worktree-specific unique IDs for port assignment.

```yaml
up_command: 'UI_PORT={{add 9000 worktree.unique_id}} pnpm dev'
down_command: "pkill -f 'vite.*{{add 9000 worktree.unique_id}}'"
health_endpoint: 'http://localhost:{{add 9000 worktree.unique_id}}/health'
app_url_template: 'http://localhost:{{add 9000 worktree.unique_id}}'
```

--------------------------------

### Handlebars Template Examples (Handlebars)

Source: https://github.com/preset-io/agor/blob/main/context/concepts/board-objects.md

Provides examples of Handlebars templates demonstrating how to dynamically insert session information into prompts for zone triggers. Includes examples for issue URLs, descriptions, and custom context.

```handlebars
Review the code and comment on {{session.issue_url}}

```

```handlebars
Create a subsession for {{session.description}} - Sprint {{session.context.sprintNumber}}

```

```handlebars
Add tests for PR {{session.pull_request_url}} (Team: {{session.context.teamName}})

```

--------------------------------

### Agor MCP Server CLI Command Usage (Bash)

Source: https://github.com/preset-io/agor/blob/main/context/archives/agor-mcp-server.md

Demonstrates the command-line usage for starting the Agor MCP server and provides an example of communication between an agent SDK and the MCP server via stdin/stdout.

```bash
# New CLI command to start MCP server
agor mcp serve

```

```bash
# Agent SDK spawns this as subprocess
agor mcp serve

# Communicates via stdin/stdout
# Agent sends: { "method": "tools/list" }
# MCP responds: { "tools": [...] }

```

--------------------------------

### Start Agor Daemon

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/api-reference/index.mdx

Command to start the Agor daemon. This command is essential for enabling the interactive API documentation and other daemon functionalities. It requires no specific input parameters.

```bash
agor daemon start
```

--------------------------------

### Gemini API Streaming Example

Source: https://github.com/preset-io/agor/blob/main/context/archives/gemini-integration-research.md

Demonstrates how to stream content from the Gemini API, including handling function calls. This example is for the Gemini API (not the CLI) and shows how to process streaming chunks.

```javascript
const result = await model.generateContentStream({
  contents: [{ role: 'user', parts: [{ text: prompt }] }],
  tools: [{ functionDeclarations: [...] }]
});

for await (const chunk of result.stream) {
  // Process streaming chunks
}
```

--------------------------------

### Install OpenCode CLI (Bash)

Source: https://github.com/preset-io/agor/blob/main/context/archives/opencode-integration.md

Installs the OpenCode command-line interface globally using npm. This is a prerequisite for running OpenCode commands.

```bash
npm install -g @opencode-ai/cli
```

--------------------------------

### Start OpenCode Server (Bash)

Source: https://github.com/preset-io/agor/blob/main/context/projects/opencode.md

Command to start the OpenCode server. It specifies the port and can be run with a verbose flag for increased logging, which is useful for debugging.

```bash
opencode serve --port 4096

opencode serve --port 4096 --verbose
```

--------------------------------

### Start OpenCode Server (Bash)

Source: https://github.com/preset-io/agor/blob/main/context/archives/opencode-integration.md

Starts the OpenCode server on a specified port. This command should be left running while using OpenCode features.

```bash
opencode serve --port 4096
```

--------------------------------

### Install Agent SDK and Remove Old SDK

Source: https://github.com/preset-io/agor/blob/main/context/concepts/agent-integration.md

Commands to install the Agent SDK and remove the older basic SDK. This is a crucial first step in the migration process.

```bash
cd packages/core
pnpm add @anthropic-ai/claude-agent-sdk
pnpm remove @anthropic-ai/sdk  # Remove basic SDK
```

--------------------------------

### Ant Design Component Installation (Bash)

Source: https://github.com/preset-io/agor/blob/main/context/archives/user-comments-and-conversation.md

Lists the necessary Ant Design and related packages for frontend development, specifically for implementing the comment UI. These packages are confirmed to be already installed in the project. Dependencies include 'antd', '@ant-design/x', and 'emoji-picker-react'.

```bash
# Already installed:
# - antd (for List, Avatar, Space, etc.)
# - @ant-design/x (for Sender)
# - emoji-picker-react (for reactions)
```

--------------------------------

### Agor Configuration Example (YAML)

Source: https://github.com/preset-io/agor/blob/main/context/concepts/auth.md

Example YAML configuration for the Agor daemon, demonstrating how to control authentication settings. It shows options to allow anonymous access and to require authentication.

```yaml
# ~/.agor/config.yaml
daemon:
  allowAnonymous: true # Allow unauthenticated access (default)
  requireAuth: false # Require authentication (opt-in)
```

--------------------------------

### MCP Environment Start Tool Implementation (TypeScript)

Source: https://github.com/preset-io/agor/blob/main/context/archives/environment-logs-and-mcp.md

Defines the 'agor_environment_start' MCP tool, responsible for initiating an environment for a specified worktree. It utilizes Zod for input validation and interacts with the worktree service to start the environment, returning success status, output, and any errors.

```typescript
import {
  z,
} from 'zod';
import { McpTool } from '../types';
import {
  worktreeService,
} from '../../services/worktrees/worktrees.class';

export const environmentStartTool: McpTool = {
  name: 'agor_environment_start',
  description: 'Start the environment for a worktree',
  inputSchema: z.object({
    worktreeId: z.string(),
  }),
  async handler({ worktreeId }) {
    try {
      const result = await worktreeService.startEnvironment(worktreeId);
      return {
        success: true,
        output: result.output,
        error: result.error || null,
      };
    } catch (error) {
      return {
        success: false,
        output: null,
        error: error.message,
      };
    } 
  },
};

// Similar implementations for stop, health, logs, openApp
```

--------------------------------

### Daemon Startup Migration Bootstrap

Source: https://github.com/preset-io/agor/blob/main/context/archives/database-migrations.md

Illustrates the daemon startup process in TypeScript, including checking for the existence of the migrations table and bootstrapping migrations if it's the first run with the new migration system.

```typescript
// In daemon startup (apps/agor-daemon/src/index.ts)

async function startDaemon() {
  const db = createDatabase({ url: dbPath });

  // Check if migrations table exists
  const hasMigrations = await checkMigrationsTable(db);

  if (!hasMigrations) {
    // First time with new migration system
    await bootstrapMigrations(db);
  }

  // Now run normal migrations
  await runMigrations(db);

  // ... rest
}
```

--------------------------------

### Docker Development Setup - Agor

Source: https://github.com/preset-io/agor/blob/main/README.md

Instructions for setting up the Agor development environment using Docker Compose.

```bash
docker compose up
```

--------------------------------

### Database Migration System Setup

Source: https://github.com/preset-io/agor/blob/main/context/archives/user-comments-and-conversation.md

Code snippets illustrating the process for establishing a database migration system, including schema definition, SQL migration scripts, and automated initialization.

```typescript
// Example schema definition
// packages/core/src/db/schema.ts
// ... schema definitions ...

// Example migration script
// packages/core/src/db/migrate.ts
export async function createInitialSchema(db: Drizzle<YourDatabaseSchema>) {
  await db.executeRaw`CREATE TABLE IF NOT EXISTS board_comments (
    id UUID PRIMARY KEY,
    board_id UUID NOT NULL,
    session_id UUID,
    content TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
  )`;
  // ... other table creations ...
}

// Example daemon initialization
// apps/agor-daemon/src/index.ts
import { initializeDatabase } from '@preset-io/core/db';

async function startServer() {
  // ... other setup ...
  await initializeDatabase();
  // ... start server ...
}
```

--------------------------------

### Add Markdown Support with React Markdown

Source: https://github.com/preset-io/agor/blob/main/context/archives/user-comments-and-conversation.md

This snippet demonstrates how to integrate the `react-markdown` library to render markdown content within the application. It includes instructions for installation and a basic usage example.

```bash
pnpm add react-markdown
```

```tsx
import ReactMarkdown from 'react-markdown';

<Bubble content={<ReactMarkdown>{comment.content}</ReactMarkdown>} />;
```

--------------------------------

### Install Default VS Code Extensions (TypeScript)

Source: https://github.com/preset-io/agor/blob/main/context/explorations/ide-integration.md

A function that installs a predefined list of default VS Code extensions for code-server. It iterates through a `DEFAULT_EXTENSIONS` array and executes the `code-server --install-extension` command for each. This is typically used during the setup or initialization of the IDE environment. It requires the ability to execute shell commands.

```typescript
// packages/core/src/services/ide-manager.ts

const DEFAULT_EXTENSIONS = [
  'dbaeumer.vscode-eslint',
  'esbenp.prettier-vscode',
  'ms-vscode.vscode-typescript-next',
  // Add more default extensions
];

async function installExtensions(dataDir: string): Promise<void> {
  for (const extension of DEFAULT_EXTENSIONS) {
    await exec(`code-server --install-extension ${extension} --user-data-dir ${dataDir}`);
  }
}
```

--------------------------------

### Agor Project: Quick Start Development Workflow

Source: https://github.com/preset-io/agor/blob/main/CLAUDE.md

This bash script outlines the simplified two-process workflow for starting the Agor development environment. It involves running the daemon in one terminal and the UI development server in another. It also provides crucial instructions for AI agents regarding development mode and avoiding compilation.

```bash
# Terminal 1: Daemon (watches core + daemon, auto-restarts)
cd apps/agor-daemon
pnpm dev

# Terminal 2: UI dev server
cd apps/agor-ui
pnpm dev
```

--------------------------------

### Use Cases for agor_sessions_create (TypeScript)

Source: https://github.com/preset-io/agor/blob/main/context/archives/mcp-session-management.md

These TypeScript examples demonstrate how to use the `agor_sessions_create` function for various scenarios, including starting new work, using different agents, and configuring permissions.

```typescript
// Start fresh work in existing worktree (uses default permission mode)
agor_sessions_create({
  worktreeId: '019a1234',
  agenticTool: 'claude-code',
  title: 'Add authentication tests',
  description: 'Write comprehensive tests for the auth flow',
  contextFiles: ['context/concepts/auth.md'],
  // permissionMode defaults to 'acceptEdits' for claude-code
});

// Create session for different agent in same worktree
agor_sessions_create({
  worktreeId: '019a1234',
  agenticTool: 'codex',
  title: 'Document API endpoints',
  mcpServerIds: ['019b5678'], // Attach filesystem MCP
  boardId: '019c9abc',
  // permissionMode defaults to 'auto' for codex
});

// Create session with strict permissions for untrusted code
agor_sessions_create({
  worktreeId: '019a1234',
  agenticTool: 'claude-code',
  title: 'Review external PR',
  permissionMode: 'default', // Ask for every tool use
});
```

--------------------------------

### List and Get Tasks (REST API)

Source: https://context7.com/preset-io/agor/llms.txt

Provides examples for listing tasks associated with a session, filtering tasks by their status, and retrieving specific task details including usage statistics.

```bash
# List tasks for a session
curl "http://localhost:3030/tasks?session_id=01933e4a-ফের..."

# Filter running tasks
curl "http://localhost:3030/tasks?status=running"

# Get task with usage stats
curl http://localhost:3030/tasks/01933e4a
```

--------------------------------

### Setup Query with Thinking Budget in TypeScript

Source: https://github.com/preset-io/agor/blob/main/context/archives/thinking-mode.md

This TypeScript function `setupQuery` integrates with a query builder to resolve and apply a thinking budget based on session configuration and prompt analysis. It imports `resolveThinkingBudget` and uses session repository dependencies to determine the appropriate token count for thinking, logging the outcome.

```typescript
import { resolveThinkingBudget } from './thinking-detector';

export async function setupQuery(
  sessionId: SessionID,
  prompt: string,
  deps: QuerySetupDeps,
  options: { /* ... */ } = {}
): Promise<{ /* ... */ }> {
  // ... existing code ...

  const session = await deps.sessionsRepo.findById(sessionId);

  // Resolve thinking budget based on mode + prompt
  const thinkingBudget = resolveThinkingBudget(prompt, {
    thinkingMode: session.model_config?.thinkingMode,
    manualThinkingTokens: session.model_config?.manualThinkingTokens,
  });

  if (thinkingBudget !== null) {
    queryOptions.maxThinkingTokens = thinkingBudget;
    console.log(`🧠 Thinking budget: ${thinkingBudget} tokens`);
  } else {
    console.log(`🧠 Thinking disabled`);
  }

  // ... rest of setup ...
}
```

--------------------------------

### Run Storybook for UI Preview (Bash)

Source: https://github.com/preset-io/agor/blob/main/apps/agor-ui/src/components/ToolUseRenderer/renderers/README.md

Provides the bash command to start the Storybook development server for previewing UI components, specifically custom tool renderers. After running, users navigate to the component in the Storybook interface.

```bash
cd apps/agor-ui
pnpm storybook
# Navigate to: Tool Renderers > [Your Renderer]

```

--------------------------------

### code-server CLI Usage for Agor

Source: https://github.com/preset-io/agor/blob/main/context/explorations/ide-integration.md

Demonstrates how to use the code-server command-line interface to launch IDE instances for Agor. Covers basic command structure, essential flags for binding address, authentication, telemetry, and user data directories.

```bash
# Basic command structure
code-server [workspace-path] --bind-addr <host:port> [flags]

# Example for Agor with specific worktree and configuration
code-server ~/.agor/worktrees/org/repo/main \
  --bind-addr 127.0.0.1:8081 \
  --auth none \
  --disable-telemetry \
  --user-data-dir ~/.agor/ide-data/worktree-123

# Alternative using environment variable for port
PORT=8081 code-server ~/.agor/worktrees/org/repo/main --auth none

```

--------------------------------

### Agor CLI: Configuration Management

Source: https://context7.com/preset-io/agor/llms.txt

Commands to get, set, and unset configuration values for Agor, typically stored in ~/.agor/config.yaml. Examples show managing daemon URL, UI port, and database path.

```bash
# Get configuration value
agor config get daemon.url
agor config get ui.port

# Set configuration value
agor config set daemon.url http://localhost:3030
agor config set ui.port 5174
agor config set database.path ~/.agor/agor.db

# Unset configuration value
agor config unset daemon.url
```

--------------------------------

### Define FeathersJS Service (TypeScript)

Source: https://github.com/preset-io/agor/blob/main/context/concepts/architecture.md

Example of defining a FeathersJS service in TypeScript for managing 'Session' entities. It includes methods for finding, getting, creating, and custom actions like 'fork'. This service definition automatically generates REST endpoints and WebSocket events.

```typescript
// agor-daemon/src/services/sessions/sessions.service.ts
export class SessionService implements ServiceMethods<Session> {
  constructor(private db: DrizzleClient) {}

  async find(params: Params): Promise<Paginated<Session>> {
    return await this.db.select().from(sessions).all();
  }

  async get(id: string): Promise<Session> {
    return await resolveShortId(this.db, sessions, id);
  }

  async create(data: Partial<Session>): Promise<Session> {
    const session = { ...data, session_id: generateId() };
    return await this.db.insert(sessions).values(session).returning().get();
  }

  // Custom methods for fork/spawn
  async fork(id: string, prompt: string): Promise<Session> {
    const parent = await this.get(id);
    return await this.create({
      ...parent,
      session_id: generateId(),
      genealogy: { forked_from_session_id: id, ... },
      description: prompt,
    });
  }
}
```

--------------------------------

### Gemini Session Creation with Model Selection

Source: https://github.com/preset-io/agor/blob/main/context/archives/gemini-integration-research.md

This example shows how to create a new Gemini session, specifying the working directory, the desired model, and an initial prompt. It illustrates dynamic model selection for different task complexities.

```typescript
import { GeminiTool } from '@google/gemini-cli-core';

async function createGeminiSession() {
  const geminiTool = new GeminiTool(); // Assuming GeminiTool is a wrapper or service
  const sessionId = 'your-session-id';

  const session = await geminiTool.createSession({
    workingDirectory: '/path/to/project',
    model: 'gemini-2.5-flash', // or 'gemini-2.5-pro', 'gemini-2.5-flash-lite'
    initialPrompt: 'Add user authentication',
  });

  // ... further session handling ...
}
```

--------------------------------

### JSON-RPC Tools List Method (JSON)

Source: https://github.com/preset-io/agor/blob/main/context/concepts/architecture.md

Demonstrates the JSON-RPC 'tools/list' method request and response. The request has no parameters, and the response includes a list of available tools, each with its name and other properties.

```json
Request:  { "method": "tools/list" }
Response: { "result": { "tools": [{ "name": "agor_sessions_list", ... }] } }
```

--------------------------------

### Run Agor Daemon and UI Locally

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/guide/development.mdx

This two-terminal workflow enables local development of Agor with pnpm. The first terminal starts the daemon, which watches for changes in core packages and automatically restarts. The second terminal runs the UI development server, providing instant HMR/hot-reloads.

```bash
# Terminal 1: Daemon (watches @agor/core + daemon, auto-restarts)
cd apps/agor-daemon
pnpm dev

# Terminal 2: UI dev server (Vite HMR for instant updates)
cd apps/agor-ui
pnpm dev

# Visit http://localhost:5173
```

--------------------------------

### Execute OpenCode Task via SDK (TypeScript)

Source: https://github.com/preset-io/agor/blob/main/context/archives/opencode-integration.md

This function executes an OpenCode task by spawning an SDK server per request. It creates a new OpenCode instance, allocates a port, starts a session, sends a prompt, and then closes the server. This approach utilizes the full SDK capabilities but incurs cold boot overhead and complexity in port allocation. Dependencies include the OpenCode SDK and a port allocation mechanism. It takes a prompt string as input and returns a Promise that resolves when the task is complete.

```typescript
async function executeTask(prompt: string) {
  const opencode = await createOpencode({
    port: await allocatePort()
  });

  try {
    const session = await opencode.client.sessions.create();
    await opencode.client.sessions.prompt({ sessionId: session.id, prompt });
  } finally {
    await opencode.server.close();
  }
}
```

--------------------------------

### Illustrative Prompt Comparison (Without Zones)

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/faq.mdx

Example of a manual prompt without using Agor's zone feature, showing the need for copy-pasting issue URLs.

```text
You: "Review this code. Here's the issue: https://github.com/..."
     (repeat for every review)
```

--------------------------------

### Run Multiple Docker Compose Instances

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/guide/development.mdx

This example demonstrates how to run multiple instances of Agor in parallel by specifying unique ports for the daemon and UI. The `-p` flag is used to ensure isolated volumes and prevent container naming conflicts, which is useful when working on different branches simultaneously.

```bash
# Main branch
cd ~/code/agor
docker compose up  # :3030 (daemon), :5173 (UI)

# Feature branch 1
cd ~/code/agor-feature-auth
PORT=4030 VITE_PORT=5174 docker compose -p agor-feature-auth up

# Feature branch 2
cd ~/code/agor-feature-payments
PORT=5030 VITE_PORT=5175 docker compose -p agor-feature-payments up
```

--------------------------------

### Illustrative Prompt Comparison (With Zones)

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/faq.mdx

Example of using Agor's zone feature, where dragging a worktree to a zone automatically injects relevant context like issue and PR links.

```text
You: *drag worktree to "Ready for Review" zone*
AI: "Reviewing implementation of https://github.com/myorg/repo/issues/123..."
     (issue/PR links auto-injected)
```

--------------------------------

### Agor Agent Self-Awareness: Get Current Session

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/guide/architecture.mdx

An example of an agent using an Agor MCP tool to understand its own execution context. This specific tool, `agor_sessions_get_current()`, returns details about the current session, including its ID, the agentic tool being used, worktree ID, board ID, and status.

```typescript
→ agor_sessions_get_current()
← {
    session_id: "019a1...",
    agentic_tool: "claude-code",
    worktree_id: "019a2...",
    board_id: "019a3...",
    status: "running"
  }
```

--------------------------------

### List Running Sessions on a Board

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/guide/architecture.mdx

This example demonstrates how to list currently running sessions associated with a specific board. It first retrieves the current session to get the board ID, then uses that ID to query for all running sessions on the same board. The output includes session IDs, agent tools, and titles.

```javascript
User: "What other sessions are running on this board?"

Agent thinking:
→ agor_sessions_get_current()
← { session_id: "019a1...", board_id: "019a2...", status: "running" }

→ agor_sessions_list({ boardId: "019a2...", status: "running" })
← { total: 3, data: [
    { session_id: "019a3...", agentic_tool: "claude-code", title: "Schema design" },
    { session_id: "019a4...", agentic_tool: "claude-code", title: "API implementation" }
  ]}

Agent: "There are 2 other sessions running on this board:
       - Session 019a3... (Claude Code, schema design)
       - Session 019a4... (Claude Code, API implementation)"
```

--------------------------------

### TypeScript: Auto-Configure MCP Servers in Claude Sessions

Source: https://github.com/preset-io/agor/blob/main/context/concepts/architecture.md

This TypeScript code snippet demonstrates how to automatically inject MCP server configurations, specifically for Agor, when starting Claude sessions. It checks for an MCP token and configures the 'agor' MCP server with an HTTP endpoint, enabling agents to access Agor MCP tools without manual setup.

```typescript
// prompt-service.ts
export async function setupQuery(...) {
  const mcpToken = session.mcp_token;

  if (mcpToken) {
    options.mcpServers = {
      agor: {
        name: 'agor',
        type: 'http',
        url: `http://localhost:3030/mcp?sessionToken=${mcpToken}`
      }
    };
  }
}
```

--------------------------------

### Configure Agent SDK for Claude Code Prompt

Source: https://github.com/preset-io/agor/blob/main/context/concepts/architecture.md

Demonstrates how to configure the Agent SDK to load CLAUDE.md automatically and use a preset system prompt. It shows the necessary import, query function call with session details, and how to handle streamed text responses using an async generator.

```typescript
import { query } from '@anthropic-ai/claude-agent-sdk';

const result = query({
  prompt: userPrompt,
  options: {
    cwd: session.repo.cwd, // Working directory for file access
    systemPrompt: {
      type: 'preset',
      preset: 'claude_code', // Loads Claude Code system prompt
    },
    settingSources: ['project'], // Auto-loads CLAUDE.md!
    model: 'claude-sonnet-45-20250929',
    allowedTools: [], // Disable tools for now (messages-only mode)
  },
});

// Stream responses (async generator)
for await (const chunk of result) {
  if (chunk.type === 'text') {
    // Handle text chunk
  }
}
```

--------------------------------

### IDE Connection Steps UI in React

Source: https://github.com/preset-io/agor/blob/main/context/explorations/ide-integration.md

This React component provides a user interface for connecting to an IDE via SSH. It utilizes an Ant Design Steps component to guide the user through three main stages: copying the SSH configuration, adding it to their SSH config file, and finally connecting via VS Code. This visualizes the setup process for a smoother user experience.

```tsx
import React from 'react';
import { Card, Button, Steps, message } from 'antd';

// Mock components and types for demonstration
interface Worktree {
  name: string;
  path: string;
}

interface CardProps {
  title: string;
  children: React.ReactNode;
}

interface StepProps {
  title: string;
  description: React.ReactNode;
}

interface StepsProps {
  children: React.ReactNode;
}

const Card: React.FC<CardProps> = ({ title, children }) => <div><h2>{title}</h2>{children}</div>;
const Steps: React.FC<StepsProps> = ({ children }) => <div>{children}</div>;
const Step: React.FC<StepProps> = ({ title, description }) => <div><h3>{title}</h3><p>{description}</p></div>;
const message = { success: (msg: string) => console.log(msg) };

// Mock function to generate SSH config
const generateSSHConfig = (worktree: Worktree): string => {
  return `
Host agor-${worktree.name}
  HostName example.com
  User agordev
  Port 22
  IdentityFile ~/.ssh/id_rsa
  RemoteCommand cd ${worktree.path} && exec $SHELL
  RequestTTY yes
`.trim();
};

const IdeConnectionSteps: React.FC<{ worktree: Worktree }> = ({ worktree }) => {
  const sshConfigContent = generateSSHConfig(worktree);

  const copyConfig = async () => {
    await navigator.clipboard.writeText(sshConfigContent);
    message.success('SSH config copied to clipboard!');
  };

  return (
    <Card title="Connect Your IDE">
      <Steps>
        <Step
          title="Copy SSH Config"
          description={
            <>
              <pre>{sshConfigContent}</pre>
              <Button onClick={copyConfig}>Copy to Clipboard</Button>
            </>
          }
        />
        <Step title="Add to ~/.ssh/config" description="Paste the config into your SSH config file" />
        <Step
          title="Connect in VS Code"
          description={<>Open VS Code → Remote SSH: Connect to Host → Select "agor-{worktree.name}"</>}
        />
      </Steps>
    </Card>
  );
};

export default IdeConnectionSteps;

```

--------------------------------

### Agor CLI: Initialization and Opening UI

Source: https://context7.com/preset-io/agor/llms.txt

Commands for initializing Agor for first-time use, which creates necessary configuration files and directories. The 'open' command launches the Agor UI in a web browser.

```bash
# Initialize Agor
agor init

# Creates:
# - ~/.agor/config.yaml
# - ~/.agor/agor.db
# - ~/.agor/repos/
# - ~/.agor/worktrees/

# Open UI in browser
agor open
```

--------------------------------

### Worktree Custom Context JSON Example

Source: https://github.com/preset-io/agor/blob/main/apps/agor-docs/pages/faq.mdx

Example of a JSON object for custom context on a worktree. This can include details such as priority, estimated effort, and dependencies.

```json
{
  "priority": "P0",
  "estimated_hours": 8,
  "dependencies": ["auth-backend", "user-service"]
}
```

--------------------------------

### Manual Testing: Schema Change and Migration Application

Source: https://github.com/preset-io/agor/blob/main/context/archives/database-migrations.md

Instructions for manually testing schema changes, including editing the schema file, generating SQL, applying the migration, and verifying the changes.

```bash
# 2. Test schema change
# Edit schema.ts (add column)
pnpm db:generate
# Verify: SQL generated correctly

# 3. Test migration application
agor db migrate
# Verify: New column exists
```

--------------------------------

### Check code-server Installation Status in TypeScript

Source: https://github.com/preset-io/agor/blob/main/context/explorations/ide-integration.md

A TypeScript function that asynchronously checks if code-server is installed by executing the 'code-server --version' command. It uses Node.js's 'child_process' and 'util' modules. The function returns a boolean indicating installation status and logs messages to the console.

```typescript
// apps/agor-daemon/src/startup/check-dependencies.ts

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

export async function checkCodeServerInstalled(): Promise<boolean> {
  try {
    const { stdout } = await execAsync('code-server --version');
    console.log(`✅ code-server installed: ${stdout.trim()}`);
    return true;
  } catch {
    console.error('❌ code-server not installed');
    console.error('   Install: brew install code-server');
    return false;
  }
}

// Run on daemon startup
const hasCodeServer = await checkCodeServerInstalled();
if (!hasCodeServer) {
  console.warn('⚠️  IDE features will be disabled');
}
```

--------------------------------

### Auto-run Migrations on Daemon Startup (TypeScript)

Source: https://github.com/preset-io/agor/blob/main/context/archives/database-migrations.md

This TypeScript code snippet demonstrates how to integrate database migrations into the Agor daemon's startup sequence. It imports `createDatabase`, `runMigrations`, and `seedInitialData` from the core library, initializes the database connection, and then executes pending migrations followed by initial data seeding. This ensures the database is always up-to-date when the daemon starts.

```typescript
// apps/agor-daemon/src/index.ts

import { createDatabase, runMigrations, seedInitialData } from '@agor/core/db';

// ... existing imports

async function startDaemon() {
  const db = createDatabase({ url: dbPath });

  // Run migrations on startup (safe to call every time)
  await runMigrations(db);

  // Seed default data if needed
  await seedInitialData(db);

  // ... rest of daemon setup
}

```