@enruana/claude-orka
Advanced tools
SDK for orchestrating Claude Code sessions with tmux - Branch management for conversations
SDK and CLI for orchestrating Claude Code sessions with tmux - Branch management for AI conversations
Claude-Orka is a powerful SDK, CLI, and UI tool that enables you to:
Perfect for complex development workflows where you need to explore multiple solutions in parallel!
npm install -g @enruana/claude-orka
# Install all dependencies automatically
orka prepare
# Verify installation
orka doctor
macOS:
brew install tmux
Ubuntu/Debian:
sudo apt-get install tmux
Claude CLI: Download from claude.ai/download
# 1. Install dependencies
orka prepare
# 2. Initialize in your project
orka init
# 3. Create a new session
orka session create "Implement Feature X"
# → Opens Claude Code in tmux
# → Opens Electron UI for visual management
# 4. Create a fork to explore an alternative
orka fork create <session-id> "Try Alternative Approach"
# 5. Export and merge the fork back to main
orka merge auto <session-id> <fork-id>
# 6. Check project status
orka status
.claude-orka/state.jsonThe custom theme makes it easy to distinguish Claude-Orka managed sessions from regular tmux sessions. The orange branding 🎭 appears in the status bar, with the session name and project information clearly visible.
Customization:
To modify the theme, edit .tmux.orka.conf in your Claude-Orka installation:
# Find your global installation
npm root -g
# Edit the config
vim $(npm root -g)/@enruana/claude-orka/.tmux.orka.conf
Or create your own theme file and source it manually:
# After creating a session
tmux source-file ~/.my-custom-theme.conf -t <session-name>
Key Features of the Theme:
orka prepareInstall and configure system dependencies automatically.
orka prepare [options]
Options:
-y, --yes - Skip confirmation promptsWhat it does:
Example:
# Interactive installation
orka prepare
# Skip confirmations
orka prepare --yes
orka doctorCheck system dependencies and configuration.
orka doctor
What it checks:
Example output:
✓ Node.js v20.18.0
✓ tmux 3.5a
✓ Claude CLI installed
✓ Project initialized
orka initInitialize Claude-Orka in the current project.
orka init
What it does:
.claude-orka/ directorystate.json with empty stateorka statusShow project status and session summary.
orka status [options]
Options:
--json - Output in JSON formatExample:
orka status
# Output:
# 📊 Project Summary
# ──────────────────
# Project Path: /path/to/project
# Total Sessions: 3
# Active: 1
# Saved: 2
# Last Updated: 11/20/2025, 6:48:46 AM
#
# 📝 Sessions:
# ✓ Feature Implementation
# ID: abc123...
# Status: active
# Total Forks: 2
orka session createCreate a new Claude Code session.
orka session create [name] [options]
Arguments:
name - Optional session name (default: "Session-{timestamp}")Options:
--no-terminal - Don't open terminal window--no-ui - Don't launch Electron UIWhat it does:
Example:
# Create with custom name
orka session create "OAuth Implementation"
# Create without opening terminal
orka session create --no-terminal
# Create without UI
orka session create --no-ui
orka session listList all sessions in the project.
orka session list [options]
Options:
--status <status> - Filter by status (active, saved)--json - Output in JSON formatExample:
# List all sessions
orka session list
# List only active sessions
orka session list --status active
# Get JSON output
orka session list --json
orka session getGet detailed information about a session.
orka session get <session-id> [options]
Arguments:
session-id - Session ID to retrieveOptions:
--json - Output in JSON formatExample:
orka session get abc123
orka session resumeResume a saved or detached session.
orka session resume <session-id> [options]
Arguments:
session-id - Session ID to resumeOptions:
--no-terminal - Don't open terminal window--no-ui - Don't launch Electron UIWhat it does:
Recovery mechanism:
Example:
orka session resume abc123
orka session closeClose and save a session for later.
orka session close <session-id>
Arguments:
session-id - Session ID to closeWhat it does:
Example:
orka session close abc123
orka session deletePermanently delete a session.
orka session delete <session-id>
Arguments:
session-id - Session ID to deleteWhat it does:
Example:
orka session delete abc123
orka fork createCreate a fork (conversation branch) from main or another fork.
orka fork create <session-id> [name] [options]
Arguments:
session-id - Parent session IDname - Optional fork name (default: "Fork-{timestamp}")Options:
--parent <parent-id> - Parent fork ID (default: "main")--vertical - Split pane vertically instead of horizontallyWhat it does:
Limitation:
Example:
# Create fork from main
orka fork create abc123 "Try JWT Implementation"
# Create fork from another fork
orka fork create abc123 "Nested Approach" --parent def456
# Create with vertical split
orka fork create abc123 --vertical
orka fork listList all forks in a session.
orka fork list <session-id> [options]
Arguments:
session-id - Session IDOptions:
--json - Output in JSON formatExample:
orka fork list abc123
orka fork resumeResume a saved fork.
orka fork resume <session-id> <fork-id>
Arguments:
session-id - Session IDfork-id - Fork ID to resumeWhat it does:
Example:
orka fork resume abc123 def456
orka fork closeClose a fork without merging (abandon experiment).
orka fork close <session-id> <fork-id>
Arguments:
session-id - Session IDfork-id - Fork ID to closeWhat it does:
Use case:
Example:
orka fork close abc123 def456
orka fork deletePermanently delete a fork.
orka fork delete <session-id> <fork-id>
Arguments:
session-id - Session IDfork-id - Fork ID to deleteWhat it does:
Example:
orka fork delete abc123 def456
orka merge exportGenerate export summary for a fork.
orka merge export <session-id> <fork-id>
Arguments:
session-id - Session IDfork-id - Fork ID to exportWhat it does:
.claude-orka/exports/fork-{id}.mdExample:
orka merge export abc123 def456
# Wait for Claude to complete (usually 10-15 seconds)
orka merge doMerge a fork back to its parent.
orka merge do <session-id> <fork-id>
Arguments:
session-id - Session IDfork-id - Fork ID to mergePrerequisites:
What it does:
Example:
orka merge do abc123 def456
orka merge autoExport and merge a fork (recommended).
orka merge auto <session-id> <fork-id> [options]
Arguments:
session-id - Session IDfork-id - Fork ID to export and mergeOptions:
--wait <ms> - Wait time for export (default: 15000ms)What it does:
Example:
# Use default wait time (15 seconds)
orka merge auto abc123 def456
# Custom wait time (20 seconds)
orka merge auto abc123 def456 --wait 20000
import { ClaudeOrka } from '@enruana/claude-orka'
Main SDK class for orchestrating Claude Code sessions.
new ClaudeOrka(projectPath: string)
Parameters:
projectPath - Absolute path to your project directoryExample:
const orka = new ClaudeOrka('/Users/username/my-project')
await orka.initialize()
initialize()Initialize ClaudeOrka and create state directory.
async initialize(): Promise<void>
Example:
await orka.initialize()
createSession()Create a new Claude Code session.
async createSession(
name?: string,
openTerminal?: boolean
): Promise<Session>
Parameters:
name - Optional session name (default: "Session-{timestamp}")openTerminal - Open terminal window (default: true)Returns: Session object
Example:
const session = await orka.createSession('OAuth Implementation')
console.log(session.id) // abc123...
resumeSession()Resume a saved session.
async resumeSession(
sessionId: string,
openTerminal?: boolean
): Promise<Session>
Parameters:
sessionId - Session ID to resumeopenTerminal - Open terminal window (default: true)Returns: Session object
Recovery behavior:
Example:
const session = await orka.resumeSession('abc123')
closeSession()Close a session.
async closeSession(sessionId: string): Promise<void>
Parameters:
sessionId - Session ID to closeExample:
await orka.closeSession('abc123')
deleteSession()Permanently delete a session.
async deleteSession(sessionId: string): Promise<void>
Parameters:
sessionId - Session ID to deleteExample:
await orka.deleteSession('abc123')
listSessions()List sessions with optional filters.
async listSessions(filters?: SessionFilters): Promise<Session[]>
Parameters:
filters - Optional filters (status, name)Returns: Array of Session objects
Example:
// List all sessions
const sessions = await orka.listSessions()
// List only active sessions
const activeSessions = await orka.listSessions({ status: 'active' })
getSession()Get a session by ID.
async getSession(sessionId: string): Promise<Session | null>
Parameters:
sessionId - Session IDReturns: Session object or null
Example:
const session = await orka.getSession('abc123')
if (session) {
console.log(session.name)
}
getProjectSummary()Get complete project summary with statistics.
async getProjectSummary(): Promise<ProjectSummary>
Returns: ProjectSummary object
Example:
const summary = await orka.getProjectSummary()
console.log(`Total sessions: ${summary.totalSessions}`)
console.log(`Active: ${summary.activeSessions}`)
createFork()Create a fork (conversation branch).
async createFork(
sessionId: string,
name?: string,
parentId?: string,
vertical?: boolean
): Promise<Fork>
Parameters:
sessionId - Session IDname - Optional fork name (default: "Fork-{timestamp}")parentId - Parent fork ID (default: "main")vertical - Split vertically (default: false)Returns: Fork object
Example:
// Create fork from main
const fork = await orka.createFork('abc123', 'JWT Implementation')
// Create fork from another fork
const nestedFork = await orka.createFork(
'abc123',
'Nested Approach',
'def456'
)
// Create with vertical split
const vFork = await orka.createFork('abc123', undefined, 'main', true)
resumeFork()Resume a saved fork.
async resumeFork(sessionId: string, forkId: string): Promise<Fork>
Parameters:
sessionId - Session IDforkId - Fork IDReturns: Fork object
Example:
const fork = await orka.resumeFork('abc123', 'def456')
closeFork()Close a fork without merging.
async closeFork(sessionId: string, forkId: string): Promise<void>
Parameters:
sessionId - Session IDforkId - Fork IDExample:
await orka.closeFork('abc123', 'def456')
deleteFork()Permanently delete a fork.
async deleteFork(sessionId: string, forkId: string): Promise<void>
Parameters:
sessionId - Session IDforkId - Fork IDExample:
await orka.deleteFork('abc123', 'def456')
generateForkExport()Generate export summary for a fork.
async generateForkExport(
sessionId: string,
forkId: string
): Promise<string>
Parameters:
sessionId - Session IDforkId - Fork IDReturns: Path to export file (relative to project)
Note: Async - Claude generates the export in background
Example:
const exportPath = await orka.generateForkExport('abc123', 'def456')
console.log(`Export will be saved to: ${exportPath}`)
// Wait 10-15 seconds for Claude to complete
merge()Merge a fork to its parent.
async merge(sessionId: string, forkId: string): Promise<void>
Parameters:
sessionId - Session IDforkId - Fork IDPrerequisites:
Example:
await orka.merge('abc123', 'def456')
generateExportAndMerge()Generate export and merge (recommended).
async generateExportAndMerge(
sessionId: string,
forkId: string,
waitTime?: number
): Promise<void>
Parameters:
sessionId - Session IDforkId - Fork IDwaitTime - Wait time in ms (default: 15000)Example:
// Use default wait time
await orka.generateExportAndMerge('abc123', 'def456')
// Custom wait time
await orka.generateExportAndMerge('abc123', 'def456', 20000)
generateExportMergeAndClose()Complete workflow: export, merge, and close.
async generateExportMergeAndClose(
sessionId: string,
forkId: string,
waitTime?: number
): Promise<void>
Parameters:
sessionId - Session IDforkId - Fork IDwaitTime - Wait time in ms (default: 15000)Example:
await orka.generateExportMergeAndClose('abc123', 'def456')
send()Send command to session or fork.
async send(
sessionId: string,
command: string,
target?: string
): Promise<void>
Parameters:
sessionId - Session IDcommand - Command to sendtarget - Optional fork ID (default: main)Example:
// Send to main
await orka.send('abc123', 'ls -la')
// Send to fork
await orka.send('abc123', 'npm test', 'def456')
interface Session {
id: string // Unique session ID
name: string // Session name
tmuxSessionId: string // tmux session ID
status: 'active' | 'saved' // Session status
createdAt: string // ISO timestamp
lastActivity: string // ISO timestamp
main: MainBranch // Main conversation
forks: Fork[] // Array of forks
projectPath?: string // Project path
}
interface MainBranch {
claudeSessionId: string // Claude session UUID
tmuxPaneId?: string // tmux pane ID (if active)
status: 'active' | 'saved' // Branch status
contextPath?: string // Path to context export
}
interface Fork {
id: string // Fork ID
name: string // Fork name
parentId: string // Parent ID ('main' or fork ID)
claudeSessionId: string // Claude session UUID
tmuxPaneId?: string // tmux pane ID (if active)
createdAt: string // ISO timestamp
status: 'active' | 'saved' | 'closed' | 'merged' // Fork status
contextPath?: string // Path to export
mergedToMain?: boolean // Merge status
mergedAt?: string // Merge timestamp
}
interface SessionFilters {
status?: 'active' | 'saved' // Filter by status
name?: string // Filter by name (partial match)
}
interface ProjectSummary {
projectPath: string // Project path
totalSessions: number // Total sessions
activeSessions: number // Active sessions count
savedSessions: number // Saved sessions count
sessions: SessionSummary[] // Array of session summaries
lastUpdated: string // ISO timestamp
}
interface SessionSummary {
id: string // Session ID
name: string // Session name
claudeSessionId: string // Claude session UUID
status: 'active' | 'saved' // Status
createdAt: string // ISO timestamp
lastActivity: string // ISO timestamp
totalForks: number // Total forks
activeForks: number // Active forks count
savedForks: number // Saved forks count
mergedForks: number // Merged forks count
forks: ForkSummary[] // Array of fork summaries
}
interface ForkSummary {
id: string // Fork ID
name: string // Fork name
claudeSessionId: string // Claude session UUID
status: 'active' | 'saved' | 'closed' | 'merged' // Status
createdAt: string // ISO timestamp
hasContext: boolean // Has export
contextPath?: string // Path to export
mergedToMain: boolean // Merge status
mergedAt?: string // Merge timestamp
}
The Electron UI provides a visual interface for managing Claude Code sessions and forks. It automatically launches when you create or resume a session.
Active Fork with Visual Hierarchy
Visual session tree showing main branch and an active fork with parent-child relationship
Closed and Merged Forks
Compact visual representation: Red circles for closed forks, green circles for merged forks
Fork Info Modal
Detailed fork information modal with export file access for merged forks
Main Node:
Fork Nodes (Active/Saved):
Fork Nodes (Closed/Merged):
Project Name:
Code Button:
Terminal Button:
Save & Close Button:
Located at the bottom, shows actions for selected node:
New Fork:
Export:
Merge:
Close:
For closed/merged forks, clicking shows modal with:
Information displayed:
Actions:
The UI automatically updates when:
.claude-orka/state.json)Frameless design:
Automatic (default):
orka session create
# UI launches automatically
Manual control:
# Skip UI launch
orka session create --no-ui
# Launch UI programmatically
const orka = new ClaudeOrka('/path/to/project')
await orka.createSession('Feature', true) // true = open terminal + UI
import { ClaudeOrka } from '@enruana/claude-orka'
const orka = new ClaudeOrka('/Users/me/my-project')
await orka.initialize()
// Create session
const session = await orka.createSession('OAuth Implementation')
console.log(`Session created: ${session.id}`)
// Work on main... then create fork
const fork = await orka.createFork(session.id, 'Try JWT Tokens')
console.log(`Fork created: ${fork.id}`)
// Work on fork... then merge back
await orka.generateExportAndMerge(session.id, fork.id)
console.log('Fork merged!')
// Check final state
const summary = await orka.getProjectSummary()
console.log(`Total sessions: ${summary.totalSessions}`)
const orka = new ClaudeOrka(process.cwd())
await orka.initialize()
const session = await orka.createSession('Database Design')
// Create multiple forks to explore options
const fork1 = await orka.createFork(session.id, 'PostgreSQL Approach')
const fork2 = await orka.createFork(session.id, 'MongoDB Approach')
const fork3 = await orka.createFork(session.id, 'Hybrid Approach')
// Work on each... then merge the winner
await orka.generateExportAndMerge(session.id, fork1.id)
// Close the others
await orka.closeFork(session.id, fork2.id)
await orka.closeFork(session.id, fork3.id)
const session = await orka.createSession('API Design')
// Main approach
const restFork = await orka.createFork(session.id, 'REST API')
// Try variations of REST
const restV1 = await orka.createFork(
session.id,
'REST with Versioning',
restFork.id // parent is the REST fork
)
const restGraphQL = await orka.createFork(
session.id,
'REST + GraphQL Hybrid',
restFork.id
)
// Merge best variation back to REST fork
await orka.generateExportAndMerge(session.id, restV1.id)
// Then merge REST fork to main
await orka.generateExportAndMerge(session.id, restFork.id)
// Create session
const session = await orka.createSession('Long Running Task')
// ... work on it ...
// Close session (detach from tmux)
await orka.closeSession(session.id)
// Later... even after system restart
const resumed = await orka.resumeSession(session.id)
console.log('Session resumed with full context!')
// If tmux was lost (restart), ClaudeOrka:
// 1. Detects missing tmux session
// 2. Creates new tmux session
// 3. Resumes Claude session with full history
// 4. Restores all forks
#!/bin/bash
# Create session
SESSION_ID=$(orka session create "Feature X" --json | jq -r '.id')
# Create fork
FORK_ID=$(orka fork create $SESSION_ID "Alternative" --json | jq -r '.id')
# Export and merge
orka merge auto $SESSION_ID $FORK_ID
# Get final summary
orka status
.claude-orka/
├── state.json # Project state (sessions, forks)
└── exports/ # Fork export summaries
├── fork-abc123.md # Export for fork abc123
└── fork-def456.md # Export for fork def456
Location: .claude-orka/state.json
Structure:
{
"version": "1.0.0",
"projectPath": "/path/to/project",
"sessions": [
{
"id": "abc123...",
"name": "Feature Implementation",
"tmuxSessionId": "orka-abc123",
"status": "active",
"createdAt": "2025-11-20T10:00:00.000Z",
"lastActivity": "2025-11-20T12:00:00.000Z",
"main": {
"claudeSessionId": "uuid-main",
"tmuxPaneId": "%1",
"status": "active"
},
"forks": [
{
"id": "def456",
"name": "Alternative Approach",
"parentId": "main",
"claudeSessionId": "uuid-fork",
"tmuxPaneId": "%2",
"status": "merged",
"createdAt": "2025-11-20T11:00:00.000Z",
"contextPath": ".claude-orka/exports/fork-def456.md",
"mergedToMain": true,
"mergedAt": "2025-11-20T12:00:00.000Z"
}
]
}
],
"lastUpdated": "2025-11-20T12:00:00.000Z"
}
Session:
Main Branch:
Fork:
Export:
Merge:
Session naming: orka-{session-id}
Pane layout:
┌─────────────────────────────────┐
│ Main (MAIN) │
├─────────────────────────────────┤
│ Fork 1 │
├─────────────────────────────────┤
│ Fork 2 │
└─────────────────────────────────┘
Recovery:
Session detection:
~/.claude/history.jsonlContext preservation:
Error: command not found: tmux
Solution:
# macOS
brew install tmux
# Ubuntu
sudo apt-get install tmux
# Or use orka prepare
orka prepare
Error: command not found: claude
Solution:
npm install -g @anthropic-ai/claude-cliclaude --versionError: Project not initialized
Solution:
orka init
Error: Session won't resume after restart
Check:
.claude-orka/state.json~/.claude/history.jsonlorka doctor to check dependenciesRecovery:
# Force resume
orka session resume <session-id>
# If that fails, create new session
orka session create
Error: Cannot merge - fork not exported
Solution:
# Export first
orka merge export <session-id> <fork-id>
# Wait 10-15 seconds for Claude
# Then merge
orka merge do <session-id> <fork-id>
# Or use auto (recommended)
orka merge auto <session-id> <fork-id>
Error: Electron UI doesn't open
Check:
npm list -g electronManual launch:
# Check if UI process is running
ps aux | grep electron
# Kill existing UI
pkill -f "electron.*claude-orka"
# Try again
orka session resume <session-id>
Error: Fork creation blocked
Reason: Claude Code limitation - only one fork per branch
Solution:
# Merge or close existing fork first
orka merge auto <session-id> <existing-fork-id>
# Or close it
orka fork close <session-id> <existing-fork-id>
# Then create new fork
orka fork create <session-id> "New Fork"
Enable debug logging:
# Set environment variable
export CLAUDE_ORKA_DEBUG=1
# Run command
orka session create
# Check logs
cat .claude-orka/orka.log
# Check system status
orka doctor
# Get help for command
orka session create --help
# View version
orka --version
Contributions are welcome! Please feel free to submit a Pull Request.
Areas for contribution:
MIT © enruana
Made with ❤️ for the Claude Code community
FAQs
SDK for orchestrating Claude Code sessions with tmux - Branch management for conversations
The npm package @enruana/claude-orka receives a total of 10 weekly downloads. As such, @enruana/claude-orka popularity was classified as not popular.
We found that @enruana/claude-orka demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Docker and Socket have uncovered malicious Checkmarx KICS images and suspicious code extension releases in a broader supply chain compromise.
Research
Malicious Namastex.ai npm packages appear to replicate TeamPCP-style Canister Worm tradecraft, including exfiltration and self-propagation.
Product
Explore exportable charts for vulnerabilities, dependencies, and usage with Reports, Socket’s new extensible reporting framework.