Local Setup

After installing the app and connecting GitHub, there are a few things to check on your local machine to get the best experience.

Git

Git must be installed and available in your PATH. Athena uses git directly for status, diffs, branch info, and file history.

git --version   # Should print a version number

Ripgrep (Recommended)

Athena’s code search tool uses ripgrep (rg) when available. It’s significantly faster than the fallback and respects .gitignore automatically.

# macOS
brew install ripgrep

# Ubuntu/Debian
apt-get install ripgrep

If ripgrep isn’t installed, search still works — it falls back to Python regex, which is slower on large codebases.

GitHub CLI (Optional)

Athena can use the GitHub CLI (gh) through shell commands for operations like creating PRs, viewing issues, and managing releases. If you want Athena to interact with GitHub beyond what the built-in integration provides, install and authenticate it:

# macOS
brew install gh

# Authenticate
gh auth login

The QB Directory

All local state lives under a single directory — ~/.qb/ by default (or ~/.qb-dev/ for the dev environment). This includes:

File	Purpose
credentials.json	Auth tokens from the device sign-in flow
config.yml	Shell permissions, auto-approve thresholds, sandbox settings
mcp.json	MCP server configurations
repo-paths.json	Local repo directory mappings (per org)
logs/	Structured log files (one per app startup)

You don’t need to create any of these manually — the app creates them as needed.

Configuration (config.yml)

The config.yml file in your QB directory controls shell permissions, file edit thresholds, and other behavior. You can edit it directly or configure everything through Settings in the app.

# Example config.yml
shellPermissions:
  autoApprove:
    - "npm test"
    - "git log"
  autoApprovePwd:
    - "mkdir"
  block:
    - "rm -rf"

autoApproveEditThreshold: 10   # Auto-approve edits ≤ 10 lines

logging:
  level: "INFO"                 # DEBUG, INFO, WARNING, ERROR

See Permissions for the full reference on shell and file edit rules.

Logs

Log files are stored in ~/.qb/logs/ with one file per app startup (sidecar-YYYYMMDD-HHMMSS.log). They include structured traces of every operation — tool calls, permission decisions, errors with stack traces.

Useful for debugging:

• Check the latest log file to understand why a command failed
• Search for error_type to find exceptions
• Each operation has a request_id for tracing

Logs are not automatically rotated, so periodically clean old files if disk space is a concern.