Examples & Cookbook

Real-world workflows and patterns for getting the most out of Arcana. Each example includes the exact commands to run.

Code Review

Review open PRs for bugs, style issues, and security concerns.

# One-shot review
arcana run "review the open PRs for bugs and security issues"

# Interactive session
arcana
> review the last 10 commits for potential issues
> focus on error handling and edge cases

# Scheduled review (every 4 hours)
arcana cron add \
  --name "PR review" \
  --schedule "0 */4 * * *" \
  --prompt "review open PRs for bugs, security issues, and style problems"

Codebase Exploration

Understand unfamiliar code quickly.

# Quick overview
arcana run "explain the architecture of this codebase"

# Deep dive
arcana run "trace the authentication flow from login to token generation"

# Find patterns
arcana run "what design patterns are used in the src/ directory?"

# Large codebases — use Gemini's 1M context
export ARCANA_PROVIDER=google
export ARCANA_MODEL=gemini-2.5-pro
arcana run "analyze the entire codebase and identify architectural issues"

Refactoring

Plan and execute code refactoring with safety checks.

# Plan only
arcana run "plan a refactor of the database layer — don't make changes, just outline the steps"

# Execute with review
arcana
> refactor src/utils.js to use TypeScript
> show me the diff before committing
> make sure all tests still pass

# Extract a module
arcana run "extract the email sending logic into a separate module with proper error handling"

Documentation Generation

# Generate README
arcana run "write a comprehensive README.md for this project"

# API docs
arcana run "generate OpenAPI documentation for the REST endpoints in src/routes/"

# Inline docs
arcana run "add JSDoc comments to all exported functions in src/utils/"

Testing

# Write tests
arcana run "write unit tests for the UserService class — cover happy path and edge cases"

# Find gaps
arcana run "analyze test coverage and identify untested code paths"

# Fix failing tests
arcana run "the test in tests/auth.test.js is failing — diagnose and fix it"

Git Workflows

# Commit messages
arcana run "stage all changes and write a conventional commit message"

# Changelog
arcana run "generate a changelog from the last 50 commits"

# Branch cleanup
arcana run "list branches that have been merged into main and suggest which to delete"

Scheduled Automation

Set up recurring tasks with cron jobs.

# Daily standup summary
arcana cron add \
  --name "daily standup" \
  --schedule "0 9 * * 1-5" \
  --prompt "summarize yesterday's git commits and today's open issues"

# Weekly dependency audit
arcana cron add \
  --name "dep audit" \
  --schedule "0 0 * * 1" \
  --prompt "check for outdated dependencies and known vulnerabilities"

# Hourly monitoring
arcana cron add \
  --name "health check" \
  --schedule "0 * * * *" \
  --prompt "run the test suite and report any failures"

# Start the daemon
arcana cron start

Multi-Provider Patterns

Use different models for different tasks to optimize cost and quality.

# Use Claude for coding, GPT-4o for analysis
export ARCANA_PROVIDER=anthropic
export ARCANA_MODEL=claude-sonnet-4
arcana run "refactor the authentication module"

# Switch to Gemini for large context
/providers
> select Google Gemini > gemini-2.5-pro
> analyze the entire codebase for security vulnerabilities

# Use a cheap model for extraction
export ARCANA_UTILITY_MODEL=gpt-4o-mini

Memory Patterns

# Build project knowledge over time
arcana
> this project uses PostgreSQL with Drizzle ORM
> the API routes are in src/routes/
> deployment is via Cloudflare Workers

# Later sessions automatically recall these facts
arcana run "what database does this project use?"  # → PostgreSQL with Drizzle

# Search memory
arcana memory search "deployment"
arcana memory facts --topic "api"

Gateway Bot Patterns

# Team assistant on Slack
arcana gateway
# → Responds in #dev channel, remembers conversation context

# Code review bot on Discord
# Config: only responds in #code-review channel
# Uses the code-review skill automatically

# Personal assistant on Telegram
# Config: only responds to your user ID
# Has full memory access across all sessions

Progressive Autonomy

Start safe, increase capability as needed.

# Observe mode — read only
arcana run "analyze the codebase without making any changes"

# Advise mode — suggest only
arcana run "suggest improvements to the error handling"

# Ask mode — ask before acting (default)
arcana run "refactor the utils module"

# Enforce mode — act without asking
export ARCANA_AUTONOMY=enforce
arcana run "fix all linting errors in src/"

Free Tier Tips

Maximize value with free or cheap providers.

• Use Ollama locally for unlimited free inference
• Use Gemini free tier for up to 15 RPM
• Use DeepSeek for very cheap API calls
• Set utilityModel to the cheapest option for background tasks
• Use /compact to manage context and reduce token usage