Skip to content

Configuration Reference

Complete reference for Aegis configuration files.

Overview

Aegis uses multiple configuration files for different purposes:

File Purpose Format
~/.claude/settings.json Claude Code global settings JSON
~/.claude/settings.local.json Local overrides JSON
~/.claude.json MCP servers and hooks JSON
~/projects/aegis-core/.env Environment variables Key=Value
~/projects/aegis-core/docker-compose.yml Docker services YAML

~/.claude/settings.json

Global settings for Claude Code instance.

Structure

{
  "numStartups": 11,
  "hasSeenTasksHint": true,
  "tipsHistory": { ... },
  "oauthAccount": {
    "accountUuid": "bd269a99-d3af-4235-a27c-4d4c7326c2ec",
    "emailAddress": "rickoslyder@gmail.com",
    "organizationUuid": "c70a14dd-6092-4a22-9bbf-3dd707d91e5d",
    "displayName": "Richard",
    "organizationRole": "admin"
  },
  "hasCompletedOnboarding": true,
  "githubRepoPaths": {
    "aegis-agent/aegis-core": ["/home/agent/projects/aegis-core"]
  },
  "bypassPermissionsModeAccepted": true
}

Key Fields

numStartups

Number of times Claude Code has started. Used for onboarding hints.

Type: integer

oauthAccount

Anthropic account information.

Fields: - accountUuid: Unique account ID - emailAddress: Account email - organizationUuid: Organization ID - displayName: User display name - organizationRole: admin | member

Read-only: Managed by Claude Code.

githubRepoPaths

Maps GitHub repos to local paths.

Format: 

{
  "owner/repo": ["/absolute/path"]
}

Example: 

{
  "aegis-agent/aegis-core": ["/home/agent/projects/aegis-core"],
  "aegis-agent/digital-office": ["/home/agent"]
}

bypassPermissionsModeAccepted

Whether user has accepted bypass permissions mode.

Type: boolean Default: false

projects

Per-project configuration and statistics.

Format: 

{
  "/home/agent": {
    "allowedTools": [],
    "mcpServers": {},
    "hasCompletedProjectOnboarding": true,
    "lastCost": 3.49,
    "lastTotalInputTokens": 125331,
    "lastTotalOutputTokens": 13615,
    "lastModelUsage": {
      "claude-haiku-4-5-20251001": {
        "inputTokens": 123304,
        "outputTokens": 1293,
        "costUSD": 0.12976900000000002
      }
    }
  }
}

Statistics Tracked: - Token usage per model - Cost per session - Duration metrics - Lines added/removed

~/.claude/settings.local.json

Local overrides for settings.json. Not committed to git.

Example

{
  "customSettings": {
    "theme": "dark",
    "fontSize": 14
  }
}

Use for: Machine-specific settings, local preferences.

~/.claude.json

MCP servers, hooks, and plugin configuration.

Structure

{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  },
  "hooks": {
    "SessionStart": [...],
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...]
  },
  "enabledPlugins": {
    "code-simplifier@claude-plugins-official": true,
    "context7@claude-plugins-official": true
  },
  "mcpServers": {
    "filesystem": { ... },
    "docker": { ... },
    "postgres": { ... }
  }
}

env

Environment variables for Claude Code.

Format: 

{
  "VARIABLE_NAME": "value"
}

Example: 

{
  "ENABLE_LSP_TOOL": "1",
  "DEBUG_MODE": "false"
}

hooks

Lifecycle hooks for event handling.

Hook Events

Event When Triggered
SessionStart Claude Code session starts
PreToolUse Before any tool invocation
PostToolUse After tool completes
Notification System notification
Stop User stops/exits Claude Code
SubagentStart Subagent spawned
PermissionRequest Permission requested

Hook Structure

{
  "SessionStart": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "/home/agent/.claude/hooks/session-init.sh",
          "timeout": 15
        }
      ]
    }
  ]
}

Matcher Patterns

Filter which tools trigger the hook:

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [...]
    }
  ]
}

Syntax: Pipe-separated regex pattern.

Hook Types

  • command: Execute shell script/binary
  • mcp: Call MCP tool

Current Hooks

SessionStart

  • session-init.sh: Load Beads tasks, check autonomous mode

PreToolUse

  • block-sensitive-files.py: Block writes to .env, .secure/
  • bash-validator.py: Block dangerous commands (rm -rf, force push)
  • mcp-param-validator.py: Validate MCP tool parameters

PostToolUse

  • cost-tracker.sh: Log tool usage to ~/memory/tool-usage.jsonl
  • mcp-security-audit.py: Audit MCP calls for security
  • episodic-recorder.py: Record to episodic memory

Notification

  • notification-handler.sh: Forward to Discord/Telegram

Stop

  • autonomous-continue.sh: Continue during autonomous mode
  • quality-gate.sh: Session hygiene checks (git, journal, tasks)

SubagentStart

  • subagent-tracker.sh: Track subagent spawns

PermissionRequest

  • permission-evaluator.py: Evaluate permission requests

enabledPlugins

Anthropic and third-party plugins.

Format: 

{
  "plugin-name@namespace": true
}

Example: 

{
  "code-simplifier@claude-plugins-official": true,
  "context7@claude-plugins-official": true,
  "glm-plan-usage@zai-coding-plugins": true
}

mcpServers

MCP (Model Context Protocol) server configurations.

Server Structure

{
  "server-name": {
    "command": "npx",
    "args": ["-y", "package-name", "arg1"],
    "env": {
      "ENV_VAR": "value"
    }
  }
}

filesystem

File operations within allowed directory.

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/agent"]
}

Root: /home/agent

docker

Docker container management.

{
  "command": "npx",
  "args": ["-y", "mcp-server-docker"]
}

Capabilities: List, start, stop, logs, inspect containers.

postgres

PostgreSQL database operations with pgvector.

{
  "command": "npx",
  "args": ["-y", "mcp-postgres"],
  "env": {
    "DATABASE_URL": "postgresql://agent:agent@localhost:5432/aegis"
  }
}

Database: aegis Extensions: pgvector

ollama

Local LLM inference.

{
  "command": "npx",
  "args": ["-y", "ollama-mcp"],
  "env": {
    "OLLAMA_HOST": "http://127.0.0.1:11434"
  }
}

Models Available: - llama3.2:3b-instruct-q8_0: General reasoning - qwen2.5-coder:7b-instruct-q4_K_M: Code generation - nomic-embed-text:latest: Text embeddings - llava:7b-v1.6-mistral-q4_0: Vision

github

GitHub API access.

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}

Scopes: repo, read:org, read:user

playwright

Browser automation.

{
  "command": "npx",
  "args": ["-y", "@playwright/mcp"]
}

Capabilities: Navigate, screenshot, PDF, form fill.

discord

Discord messaging.

{
  "command": "npx",
  "args": ["-y", "mcp-discord"],
  "env": {
    "DISCORD_BOT_TOKEN": "MTQ1NDcxNTUzOTQ4OTI5MjQyOQ..."
  }
}

Guild ID: 1454722052777836546

Channels: - #general: 1454722053495324844 - #scratchpad: 1457830898681516137 - #logs: 1455049129313959937 - #alerts: 1455049130614329508 - #journal: 1455049131725816023 - #tasks: 1455049133189627926 - #decisions: 1460610168118055006

telegram

Telegram messaging.

{
  "command": "npx",
  "args": ["-y", "@iqai/mcp-telegram"],
  "env": {
    "TELEGRAM_BOT_TOKEN": "8595357001:AAEQlNjve9pDdgM0ibQhr1GM_6KYt6HHUfg"
  }
}

Chat ID: 1275129801

stackwiz

Docker deployment to rbnk.uk.

{
  "command": "/home/agent/.local/share/pipx/venvs/stackwiz-mcp/bin/stackwiz-mcp",
  "env": {
    "STACKWIZ_BASE_DIR": "/home/agent/stacks",
    "STACKWIZ_TEMPLATES_DIR": "/home/agent/stacks/_templates",
    "STACKWIZ_SCRIPTS_DIR": "/home/agent/stacks/_scripts",
    "STACKWIZ_CF_API_TOKEN": "XBRTcET1wQgo0jDCdEeIfWNy6fUHPYUozwRtKQa3",
    "STACKWIZ_DEFAULT_DOMAIN": "rbnk.uk",
    "STACKWIZ_DEFAULT_USER": "agent",
    "STACKWIZ_DEFAULT_GROUP": "docker",
    "STACKWIZ_DOCKER_NETWORK": "traefik_proxy"
  }
}

Capabilities: Deploy, manage, DNS configuration.

annas-archive

Book downloads from Anna's Archive.

{
  "command": "/home/agent/.local/bin/annas-mcp",
  "args": ["mcp"],
  "env": {
    "DOWNLOAD_DIR": "/home/agent/downloads"
  }
}

~/projects/aegis-core/.env

Environment variables for Aegis services.

Categories

Database

POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=5432
POSTGRES_USER=agent
POSTGRES_PASSWORD=agent
POSTGRES_DB=aegis

LLM APIs

# Z.ai (GLM-4.7)
ZAI_API_KEY=14392bf733914c24a77d2d36a2c7d4bd.z9QhBPXv2X6pwwHf
ZAI_BASE_URL=https://api.z.ai/api/anthropic/v1
ZAI_ANTHROPIC_BASE=https://api.z.ai/api/anthropic

# Fallback key
ZAI_API_KEY_FALLBACK=51a97fb60c4748e592d78bd687fba025.kJiYmb2HAfiuLnPr

# Perplexity
PERPLEXITY_API_KEY=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

Communication

# GitHub
GITHUB_TOKEN=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

# Telegram
TELEGRAM_BOT_TOKEN=8595357001:AAEQlNjve9pDdgM0ibQhr1GM_6KYt6HHUfg
TELEGRAM_CHAT_ID=1275129801

# Vonage/WhatsApp
VONAGE_API_KEY=b5e9b438
VONAGE_API_SECRET=5c4LNSMyZBYDNXht
VONAGE_APPLICATION_ID=3b60dc5c-44e6-402c-91ae-3731717bb2e7
VONAGE_WHATSAPP_NUMBER=447441443388
VONAGE_PRIVATE_KEY_B64=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t...
VONAGE_SIGNATURE_SECRET=

Payments

# Stripe
STRIPE_PUBLISHABLE_KEY=pk_live_51Sk71uGXYX2yjS5i...
STRIPE_SECRET_KEY=sk_live_51Sk71uGXYX2yjS5i...
STRIPE_WEBHOOK_SECRET=whsec_pQ65Zc2ZooSWqWrlg6O5hfOAGnsk6o03

# Email
RESEND_API_KEY=re_THdUYh4Q_KhHWxDVby6wcgRvPbopoLE8h

Services

# Aegis
AEGIS_BASE_URL=https://aegisagent.ai

# Knowledge Graph
FALKORDB_HOST=host.docker.internal
FALKORDB_PORT=6379
OLLAMA_BASE_URL=http://host.docker.internal:11434

# 3D Generation
MESHY_API_KEY=msy_OUAYIcr5ioVYJBaqMQjyi98j2WliVVBAfZP5
MESHY_WEBHOOK_SECRET=KneYsrWzJE03Lr05oa3IUHDvDvwLTxBR

See Environment Variables Reference for complete details.

~/projects/aegis-core/docker-compose.yml

Docker service definitions.

Services

dashboard

Main FastAPI application.

services:
  dashboard:
    build: .
    container_name: aegis-dashboard
    ports:
      - "8080:8080"
    environment:
      - POSTGRES_HOST=host.docker.internal
      - POSTGRES_PORT=5432
      # ... (see Environment Variables)
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /home/agent/memory:/home/agent/memory
    networks:
      traefik_proxy:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.aegis.rule=Host(`aegisagent.ai`)"
      - "traefik.http.routers.aegis.entrypoints=websecure"
      - "traefik.http.routers.aegis.tls.certresolver=cf"

Ports: 8080 (HTTP) Volumes: - Docker socket (read-only) - Memory directory - Downloads directory

Traefik Labels: - Domain: aegisagent.ai - SSL: Cloudflare resolver - Redirects: aegis.rbnk.uk → aegisagent.ai

scheduler

Background job scheduler.

services:
  scheduler:
    build: .
    container_name: aegis-scheduler
    command: ["python", "-c", "from aegis.scheduler import scheduler; scheduler.start(); import time; time.sleep(86400*365)"]
    environment:
      # Same as dashboard
    restart: unless-stopped
    depends_on:
      - dashboard
      - playwright

Purpose: Runs cron jobs, scheduled tasks.

playwright

Screenshot API for visual monitoring.

services:
  playwright:
    image: ghcr.io/vlazic/playwright-screenshot-api:latest
    container_name: aegis-playwright
    ports:
      - "3002:3000"
    restart: unless-stopped

API: http://playwright:3000

falkordb

Graph database for knowledge graph.

services:
  falkordb:
    image: falkordb/falkordb:latest
    container_name: falkordb
    command: ["redis-server", "--loadmodule", "/var/lib/falkordb/bin/falkordb.so", "TIMEOUT", "30000"]
    ports:
      - "6379:6379"   # Redis protocol
      - "3001:3000"   # Browser UI
    volumes:
      - falkordb_data:/data
    restart: unless-stopped

Protocol: Redis-compatible UI: http://localhost:3001

Networks

networks:
  traefik_proxy:
    external: true

Network: traefik_proxy (external, created by Traefik)

Volumes

volumes:
  falkordb_data:

Persistent Data: FalkorDB graph storage

Configuration Best Practices

1. Never Commit Secrets

  • Use .env for sensitive data
  • Add .env to .gitignore
  • Store credentials in ~/.secure/

2. Use Environment Variables

  • Prefer env vars over hardcoded values
  • Document required variables
  • Provide defaults where sensible

3. Separate Concerns

  • Global settings: ~/.claude/settings.json
  • MCP/hooks: ~/.claude.json
  • Application config: .env
  • Infrastructure: docker-compose.yml

4. Version Control

  • Commit: docker-compose.yml, .env.example
  • Don't commit: .env, settings.local.json

5. Documentation

  • Comment complex configurations
  • Document all environment variables
  • Provide examples

Troubleshooting

MCP Server Not Found

Problem: mcp__server__tool not available

Solution: 1. Check ~/.claude.json has server definition 2. Verify command path exists 3. Check environment variables 4. Restart Claude Code

Hook Not Executing

Problem: Hook script doesn't run

Solution: 1. Check script has execute permissions: chmod +x script.sh 2. Verify path is absolute 3. Check timeout is sufficient 4. Look for errors in logs

Docker Service Won't Start

Problem: Container fails to start

Solution: 1. Check docker-compose logs aegis-dashboard 2. Verify environment variables in .env 3. Check port conflicts: netstat -tulpn | grep 8080 4. Ensure networks exist: docker network ls

See Also