Skip to main content

​
Usage

omnara headless [OPTIONS]
Runs Claude Code in the background without a terminal UI. Perfect for dashboard-only interaction, automation, or when you want to control Claude exclusively through the web/mobile app.

​
Options

​
--prompt
string
default:"You are starting a coding session"
Initial prompt to send to Claude when the session starts
​
--permission-mode
string
Permission handling mode:
  • acceptEdits - Automatically accept all edit operations
  • bypassPermissions - Bypass all permission checks entirely
  • plan - Planning mode (Claude creates plans before executing)
  • default - Normal permission prompting behavior
​
--allowed-tools
string
Comma-separated whitelist of allowed tools (e.g., Read,Write,Bash)
​
--disallowed-tools
string
Comma-separated blacklist of disallowed tools
​
--cwd
string
Working directory for Claude (defaults to current directory)

​
Examples

# Run headless with default settings
omnara headless

​
Permission Modes

  • acceptEdits
  • bypassPermissions
  • plan
  • default
Automatically accepts all file edit operations. Claude can still ask questions via the dashboard, but file changes happen without prompts.Use case: Trusted environments where you want speed over control

​
Tool Filtering

Control which tools Claude can use:

​
Whitelist (allowed-tools)

omnara headless --allowed-tools Read,Write,Bash
Only these tools (plus mcp__omnara__approve) can be used. All others are blocked.

​
Blacklist (disallowed-tools)

omnara headless --disallowed-tools Bash,Edit
All tools except these can be used.

​
Combined

omnara headless \
  --allowed-tools Read,Write,Bash,Grep \
  --disallowed-tools Edit
Allowed tools takes precedence. Useful for fine-grained control.
The mcp__omnara__approve tool is always allowed, enabling dashboard interaction even with strict tool filtering.

​
How It Works

  1. Initialization: Creates an agent instance and connects to Omnara MCP server
  2. Initial Prompt: Sends your specified prompt to Claude
  3. Background Processing: Claude processes the request and streams responses to dashboard
  4. Message Queuing: When you respond via dashboard, messages are queued and delivered to Claude
  5. Session Persistence: Session continues until completed or explicitly ended

​
Dashboard Interaction

While Claude runs headless, you can interact via dashboard:
  • Monitor Progress: See Claude’s actions in real-time
  • Answer Questions: Respond when Claude asks for input
  • View Changes: See git diffs of file modifications
  • Control Session: End session or provide new instructions

​
Logs

Logs are stored at: 
~/.omnara/claude_headless/<session-id>.log
View logs in real-time: 
tail -f ~/.omnara/claude_headless/<session-id>.log

​
Use Cases

Automated Code Review

omnara headless \
  --prompt "Review all files for security issues" \
  --allowed-tools Read,Grep

Background Refactoring

omnara headless \
  --permission-mode acceptEdits \
  --prompt "Refactor auth module"

CI/CD Integration

omnara headless \
  --permission-mode bypassPermissions \
  --prompt "Fix linting errors"

Mobile-controlled Development

Start from your computer, control from your phone while commuting

omnara serve

Remote triggering via webhook

omnara mcp

MCP server for custom integrations