Okiro

https://github.com/ygwyg/okiro
Admin
Okiro creates isolated, ephemeral workspaces to run multiple AI agents in parallel on code...
Tokens:5,462
Snippets:41
Trust Score:5.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Get Workspace Size and Format Bytes

Source: https://context7.com/ygwyg/okiro/llms.txt

Utilities for determining the disk usage of a workspace and formatting the size in bytes into a human-readable string (e.g., '45.2 MB'). This is useful for monitoring storage consumption.

```typescript
import { getWorkspaceSize, formatBytes } from './lib/workspace.js';

const sizeBytes = await getWorkspaceSize('/path/to/workspace');
console.log(formatBytes(sizeBytes)); // "45.2 MB"
```

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

### Manage Okiro Configuration: Get, Add, Remove Projects

Source: https://context7.com/ygwyg/okiro/llms.txt

Functions for interacting with the Okiro configuration file located at `~/.okiro/config.json`. These functions allow retrieving the global configuration, project-specific configuration, adding new projects with their variations, and removing existing projects. Dependencies include the local configuration file and project paths.

```typescript
import {
  getConfig,
  getProjectConfig,
  addProject,
  removeProject,
  resolveProjectPath
} from './lib/config.js';

// Get full okiro config
const config = await getConfig();
// Returns: { version: '1.0.0', projects: { ... } }

// Get config for current project
const projectPath = resolveProjectPath(); // Uses process.cwd()
const project = await getProjectConfig(projectPath);
// Returns: ProjectConfig | null

// Add a new project with variations
const variations = [
  { id: 'var-1', path: '/home/user/.okiro/projects/my-app/var-1', createdAt: '2024-01-15T10:00:00Z' },
  { id: 'var-2', path: '/home/user/.okiro/projects/my-app/var-2', createdAt: '2024-01-15T10:00:00Z' }
];
await addProject('/path/to/my-app', variations);

// Remove project from config
await removeProject('/path/to/my-app');
```

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

### Prompt for Variation Directions Interactively

Source: https://context7.com/ygwyg/okiro/llms.txt

Interactively prompts the user for direction or style instructions for each variation of a project. This function is useful for guiding AI agents by specifying unique aspects for different development branches or variations.

```typescript
import { promptForVariationDirections } from './lib/prompt.js';

const directions = await promptForVariationDirections(3, 'add authentication');
// Prompts:
// Base task: add authentication
// Enter a direction/style for each variation:
//   var-1: use OAuth 2.0
//   var-2: use JWT tokens
//   var-3: use session cookies

// Returns: ['use OAuth 2.0', 'use JWT tokens', 'use session cookies']
```

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

### Open Web-Based Diff Viewer with okiro CLI

Source: https://context7.com/ygwyg/okiro/llms.txt

The `compare` command opens a browser-based diff viewer with features like split/unified view modes, file tree navigation, and variation tabs. It runs a local Express server.

```bash
# Open diff viewer (default port 6789)
okiro compare

# Use custom port
okiro compare --port 8080

# Don't auto-open browser
okiro compare --no-browser

# API endpoints available:
# GET /api/project     - Project info and variations list
# GET /api/all-files   - All changed files across variations
# GET /api/files/:var  - Changed files for specific variation
# GET /api/diff/:var?file=path - Diff for specific file in variation
```

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

### Apply Variation Changes to Original with okiro CLI

Source: https://context7.com/ygwyg/okiro/llms.txt

The `promote` command copies changed files from a variation back to the original codebase. It provides a preview of changes and can optionally create a git commit.

```bash
# Promote var-2 changes (with confirmation)
okiro promote var-2

# Output:
# Promoting var-2 to my-app
#
# Changed files:
#   + src/auth/login.ts
#   ~ src/app.ts
#   - src/old-auth.ts
#
# Apply these changes? [y/N]

# Skip confirmation prompt
okiro promote var-2 --force

# Promote and git commit with default message
okiro promote var-2 -c

# Promote and git commit with custom message
okiro promote var-2 -c "feat: add auth via Better Auth"
```

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

### Create Variation Workspaces with okiro CLI

Source: https://context7.com/ygwyg/okiro/llms.txt

The `spawn` command creates isolated copies of your codebase for parallel AI agent work. It utilizes efficient filesystem cloning (APFS/btrfs) and can optionally prompt for variation-specific directions.

```bash
# Create 3 variation workspaces
okiro 3

# Create 3 variations and prompt for directions per variation
okiro 3 --prompt

# Create 3 variations with a base task and per-variation directions
okiro 3 --prompt "add user authentication"
# You'll be prompted:
#   var-1: use Better Auth
#   var-2: use Clerk
#   var-3: roll our own with JWT + cookies

# Replace existing variations with new ones
okiro 3 --force

# Create variations without opening terminal sessions
okiro 3 --no-terminal
```

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

### Write AI Configuration Files

Source: https://context7.com/ygwyg/okiro/llms.txt

Writes AI agent configuration files, specifically `AGENTS.md` and `.cursor/rules`, based on the provided task and direction instructions for a specific variation. This facilitates setting up AI agents to work on isolated project variations with clear objectives.

```typescript
import { writeAIConfigFiles } from './lib/prompt.js';

await writeAIConfigFiles(
  '/path/to/variation',
  'var-1',
  'use OAuth 2.0',
  'add authentication'
);

// Creates AGENTS.md and .cursor/rules with content:
// # Okiro Variation: var-1
//
// You are working on an isolated variation of this project.
// Your changes will be compared against other variations.
//
// ## Task
// add authentication
//
// ## Direction for this variation
// use OAuth 2.0
```

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

### Configuration API

Source: https://context7.com/ygwyg/okiro/llms.txt

Interfaces for okiro's configuration and variation data.

```APIDOC
## Configuration API

### Variation Interface

**Description**: Represents a single variation workspace with its metadata.

**Fields**:
- **id** (string) - Unique identifier for the variation (e.g., "var-1", "var-2").
- **path** (string) - The full file system path to the variation workspace.
- **createdAt** (string) - The ISO 8601 timestamp when the variation was created.

**Example**:
```typescript
{
  "id": "var-1",
  "path": "/Users/user/.okiro/projects/my-app/var-1",
  "createdAt": "2023-10-27T10:00:00Z"
}
```

### ProjectConfig Interface

**Description**: Configuration for a project, including details about its variations.

**Fields**:
- **originalPath** (string) - The file system path to the original codebase.
- **variationsDir** (string) - The directory where all variation workspaces are stored.
- **variations** (Array<Variation>) - A list of currently active `Variation` objects.
- **createdAt** (string) - The ISO 8601 timestamp when the project configuration was created.

**Example**:
```typescript
{
  "originalPath": "/Users/user/projects/my-app",
  "variationsDir": "/Users/user/.okiro/projects/my-app",
  "variations": [
    {
      "id": "var-1",
      "path": "/Users/user/.okiro/projects/my-app/var-1",
      "createdAt": "2023-10-27T10:00:00Z"
    },
    {
      "id": "var-2",
      "path": "/Users/user/.okiro/projects/my-app/var-2",
      "createdAt": "2023-10-27T10:05:00Z"
    }
  ],
  "createdAt": "2023-10-27T09:55:00Z"
}
```
```

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

### Compare Directories and List Changed Files

Source: https://context7.com/ygwyg/okiro/llms.txt

Compares two directories and returns a list of files that differ, along with their modification status ('A' for Added, 'M' for Modified, 'D' for Deleted). It automatically skips common temporary or version-controlled directories and files like `node_modules`, `.git`, and build outputs.

```typescript
import { listChangedFiles, ChangedFile } from './lib/workspace.js';

const changes: ChangedFile[] = await listChangedFiles(
  '/path/to/original',
  '/path/to/variation'
);

// Returns:
// [
//   { path: 'src/auth/login.ts', status: 'A' },  // Added
//   { path: 'src/app.ts', status: 'M' },          // Modified
//   { path: 'src/old-auth.ts', status: 'D' }      // Deleted
// ]

// Automatically skips: node_modules, .git, .DS_Store, dist, build,
// .next, .nuxt, .cache, coverage, AGENTS.md, .cursor
```

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

### CLI Commands

Source: https://context7.com/ygwyg/okiro/llms.txt

Overview of the available okiro CLI commands for managing code variations.

```APIDOC
## CLI Commands

### spawn - Create Variation Workspaces

**Description**: Creates isolated copies of your codebase for parallel AI agent work. Uses efficient filesystem cloning (APFS/btrfs) when available. Optionally prompts for variation-specific directions that are written to `AGENTS.md` and `.cursor/rules` files.

**Usage**:
```bash
# Create 3 variation workspaces
okiro 3

# Create 3 variations and prompt for directions per variation
okiro 3 --prompt

# Create 3 variations with a base task and per-variation directions
okiro 3 --prompt "add user authentication"
# You'll be prompted:
#   var-1: use Better Auth
#   var-2: use Clerk
#   var-3: roll our own with JWT + cookies

# Replace existing variations with new ones
okiro 3 --force

# Create variations without opening terminal sessions
okiro 3 --no-terminal
```

### status - Show Active Variations

**Description**: Displays information about all active variations for the current project, including paths, number of changed files, and disk usage.

**Usage**:
```bash
okiro status

# Output:
# Variations for my-app:
#
#   var-1
#     Path: ~/.okiro/projects/my-app/var-1
#     Changed: 12 files
#     Size: 45.2 MB
#
#   var-2
#     Path: ~/.okiro/projects/my-app/var-2
#     Changed: 8 files
#     Size: 43.1 MB
```

### diff - CLI Diff Comparison

**Description**: Shows unified diff output between the original codebase and a variation, or between two variations. Colorized output highlights additions, deletions, and modifications.

**Usage**:
```bash
# Diff original vs first variation (var-1)
okiro diff

# Diff original vs specific variation
okiro diff var-1

# Diff between two variations
okiro diff var-1 var-2

# Diff variation against original (explicit)
okiro diff original var-2
```

### compare - Web-Based Diff Viewer

**Description**: Opens a browser-based diff viewer with split/unified view modes, file tree navigation, and variation tabs. Uses the Rose Pine theme and runs a local Express server.

**Usage**:
```bash
# Open diff viewer (default port 6789)
okiro compare

# Use custom port
okiro compare --port 8080

# Don't auto-open browser
okiro compare --no-browser

# API endpoints available:
# GET /api/project     - Project info and variations list
# GET /api/all-files   - All changed files across variations
# GET /api/files/:var  - Changed files for specific variation
# GET /api/diff/:var?file=path - Diff for specific file in variation
```

### promote - Apply Variation to Original

**Description**: Copies changed files from a variation back to the original codebase. Shows a preview of changes and optionally creates a git commit.

**Usage**:
```bash
# Promote var-2 changes (with confirmation)
okiro promote var-2

# Output:
# Promoting var-2 to my-app
#
# Changed files:
#   + src/auth/login.ts
#   ~ src/app.ts
#   - src/old-auth.ts
#
# Apply these changes? [y/N]

# Skip confirmation prompt
okiro promote var-2 --force

# Promote and git commit with default message
okiro promote var-2 -c

# Promote and git commit with custom message
okiro promote var-2 -c "feat: add auth via Better Auth"
```

### cleanup - Remove All Variations

**Description**: Removes all variation workspaces for the current project and kills associated tmux sessions. Shows disk space that will be freed.

**Usage**:
```bash
# Cleanup with confirmation
okiro cleanup

# Output:
# This will remove 3 variations (134.5 MB)
# Continue? [y/N]

# Skip confirmation
okiro cleanup --force
```
```

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

### okiro Project Configuration Interface (TypeScript)

Source: https://context7.com/ygwyg/okiro/llms.txt

Defines the configuration structure for a project managed by okiro, including paths and a list of active variations.

```typescript
interface ProjectConfig {
  originalPath: string;      // Path to original codebase
  variationsDir: string;     // Directory containing variations
  variations: Variation[];   // List of active variations
  createdAt: string;         // ISO timestamp
}
```

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

### Display Active Variations with okiro CLI

Source: https://context7.com/ygwyg/okiro/llms.txt

The `status` command displays information about active variations for the current project, including their paths, number of changed files, and disk usage.

```bash
okiro status

# Output:
# Variations for my-app:
#
#   var-1
#     Path: ~/.okiro/projects/my-app/var-1
#     Changed: 12 files
#     Size: 45.2 MB
#
#   var-2
#     Path: ~/.okiro/projects/my-app/var-2
#     Changed: 8 files
#     Size: 43.1 MB
```

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

### Perform CLI Diff Comparison with okiro

Source: https://context7.com/ygwyg/okiro/llms.txt

The `diff` command shows unified diff output between the original codebase and a variation, or between two variations. The output is colorized to highlight changes.

```bash
# Diff original vs first variation (var-1)
okiro diff

# Diff original vs specific variation
okiro diff var-1

# Diff between two variations
okiro diff var-1 var-2

# Diff variation against original (explicit)
okiro diff original var-2
```

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

### Remove All Variations with okiro CLI

Source: https://context7.com/ygwyg/okiro/llms.txt

The `cleanup` command removes all variation workspaces for the current project and kills associated tmux sessions. It displays the disk space that will be freed.

```bash
# Cleanup with confirmation
okiro cleanup

# Output:
# This will remove 3 variations (134.5 MB)
# Continue? [y/N]

# Skip confirmation
okiro cleanup --force
```

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

### Create Isolated Workspace Copy

Source: https://context7.com/ygwyg/okiro/llms.txt

Creates an isolated workspace copy using the most efficient method available for the platform. It leverages platform-specific optimizations like APFS clones on macOS or btrfs reflinks on Linux, falling back to rsync if necessary. This function is crucial for creating clean environments for development or testing.

```typescript
import { createWorkspace } from './lib/workspace.js';

// Create a workspace clone
await createWorkspace(
  '/path/to/source',
  '/path/to/destination'
);
// Uses APFS clone on macOS, btrfs reflink on Linux, or rsync fallback
```

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

### Generate All Diffs in Batch

Source: https://context7.com/ygwyg/okiro/llms.txt

Generates diffs for multiple files in a batch, typically used after identifying changed files. It takes the original and variation paths along with a list of changed files to efficiently produce diffs for all modifications.

```typescript
import { generateAllDiffs, FileDiff } from './lib/diff.js';
import { listChangedFiles } from './lib/workspace.js';

const changedFiles = await listChangedFiles(originalPath, variationPath);
const diffs: FileDiff[] = await generateAllDiffs(
  originalPath,
  variationPath,
  changedFiles
);
```

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

### Compare API Endpoints

Source: https://context7.com/ygwyg/okiro/llms.txt

API endpoints exposed by the okiro compare web server for accessing diff information.

```APIDOC
## Compare API Endpoints

### GET /api/project

**Description**: Retrieves information about the current project and a list of its active variations.

**Parameters**:
None

**Response (200)**:
- **projectInfo** (ProjectConfig) - Project configuration details.

### GET /api/all-files

**Description**: Returns a list of all files that have been modified across any of the active variations compared to the original codebase.

**Parameters**:
None

**Response (200)**:
- **allChangedFiles** (Array<string>) - An array of file paths that differ from the original.

### GET /api/files/:var

**Description**: Retrieves a list of files modified within a specific variation compared to the original codebase.

**Parameters**:
#### Path Parameters
- **var** (string) - Required - The ID of the variation (e.g., "var-1").

**Response (200)**:
- **variationChangedFiles** (Array<string>) - An array of file paths modified in the specified variation.

### GET /api/diff/:var

**Description**: Generates and returns the diff content for a specific file within a given variation compared to the original codebase.

**Parameters**:
#### Path Parameters
- **var** (string) - Required - The ID of the variation (e.g., "var-1").
#### Query Parameters
- **file** (string) - Required - The path to the file to generate the diff for.

**Response (200)**:
- **diffContent** (string) - The unified diff output for the specified file and variation.
```

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

### okiro Variation Interface (TypeScript)

Source: https://context7.com/ygwyg/okiro/llms.txt

Defines the structure for representing a single variation workspace, including its ID, path, and creation timestamp.

```typescript
interface Variation {
  id: string;        // e.g., "var-1", "var-2"
  path: string;      // Full path to variation workspace
  createdAt: string; // ISO timestamp
}
```

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

### Generate Single File Diff with Patch

Source: https://context7.com/ygwyg/okiro/llms.txt

Generates a detailed diff for a single file between an original and a variation directory. It returns the original content, the modified content, and a unified diff patch format. This is useful for understanding specific file changes.

```typescript
import { generateFileDiff, FileDiff } from './lib/diff.js';

const diff: FileDiff = await generateFileDiff(
  '/path/to/original',
  '/path/to/variation',
  'src/app.ts'
);

// Returns:
// {
//   filePath: 'src/app.ts',
//   status: 'M',
//   original: '// original content...',
//   modified: '// modified content...',
//   patch: '--- a/src/app.ts\n+++ b/src/app.ts\n@@...'
// }
```

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

### Colorize Unified Diff Output

Source: https://context7.com/ygwyg/okiro/llms.txt

Applies ANSI color codes to a unified diff output string, making it more readable in a terminal. Additions are typically shown in green, deletions in red, and hunk headers in cyan, improving the visual analysis of code changes.

```typescript
import { colorizeUnifiedDiff } from './lib/diff.js';

const coloredPatch = colorizeUnifiedDiff(diff.patch);
console.log(coloredPatch);
// Green for additions (+), red for deletions (-), cyan for @@ hunks
```
Tokens:
Raw