---
title: Examples & Cookbook
url: https://arcana.otnelhq.com/docs/examples
---

# 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.



```bash
# 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.



```bash
# 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.



```bash
# 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



```bash
# 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



```bash
# 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



```bash
# 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.



```bash
# 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.



```bash
# 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



```bash
# 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



```bash
# 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.



```bash
# 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