Crestodian — Autonomous Personal AI Operations Agent

Crestodian is a self-hosted, local-first personal AI operations agent built on top of OpenClaw. It turns Discord into a command center for autonomous task execution, local machine control, Google Workspace queries, and automated daily developer workflows.

Unlike standard conversational chatbots, Crestodian operates as an event-driven, goal-oriented agentic loop. It runs locally on host hardware, maintaining long-term memory across sessions, interacting with standard CLI tools and standard protocols, while providing human-in-the-loop governance over high-consequence system actions.

---

🎯 What Crestodian Does

• Discord as a Command Center: Interact via direct messages or dedicated server channels with streaming status updates, structured markdown reports, and interactive confirmation gates.
• Autonomous File & Terminal Operations: Execute code edits, run build pipelines, launch background processes, and analyze project repositories directly on local storage.
• Read-Only Google Workspace Queries: Read unread Gmail messages and query upcoming Google Calendar events via the read-only gog CLI integration (gmail.readonly and calendar.readonly OAuth scopes).
• Context-Aware Memory System: Persist user preferences, routine schedules, past execution results, and project context across sessions with automated memory indexing.
• Developer Workflows: Multi-stage daily check-ins, automated repository health analysis, automated build/test verification, and safe code editing loops.
• Cron & Reminders Engine: Schedule lightweight timers, one-shot reminders, and cron-triggered background task runs with proactive notification delivery.

---

🏗️ Architecture Overview

flowchart LR
    subgraph Input
        Discord["Discord DM / Channel"]
        Cron["Timer / Cron"]
    end

    subgraph Core ["Core Engine"]
        Gateway["OpenClaw Gateway"] --> Planner["Goal Planner"]
        Planner <--> Memory["Memory Manager"]
    end

    subgraph Safety
        Sandbox["Execution Sandbox"] --> Gate["Human Approval"]
    end

    subgraph Skills ["Skills"]
        S1["Reminders"]
        S2["Developer Daily"]
        S3["CLI Runners"]
        S4["Google Workspace"]
    end

    Input --> Gateway
    Planner --> Sandbox
    Gate --> Skills
    Skills --> Gateway

Loading

For an in-depth breakdown of state handling, subagent concurrency, and gateway lifecycle, see ARCHITECTURE.md.

---

🧠 Real Engineering Challenges Solved

Crestodian was designed and iteratively debugged to resolve real-world failure modes encountered during agent operation:

1. Ollama Model Storage Migration & Startup Reliability

• Problem: The Ollama desktop app did not reliably inherit a custom OLLAMA_MODELS path set at the user level, causing models to silently fail to load after restarts — compounded by the original C: drive location running low on space.
• Solution: Migrated model storage to a dedicated drive, set OLLAMA_MODELS at the Machine/System environment level, and replaced the unreliable desktop-app startup mechanism with a dedicated Windows Scheduled Task running the server binary directly. This configuration has survived multiple restarts.

2. Local Inference Context Size & Timeout Misconfiguration

• Problem: Local inference requests failed with "request exceeds the available context size" errors because the model was loaded with a default 4096-token context window.
• Solution: Increased context length to 32,768 tokens (num_ctx / OLLAMA_CONTEXT_LENGTH) and raised the local inference provider timeout to 600 seconds to accommodate slower CPU-bound generation.

3. Delivery Routing Bug (channel: vs. user: Target Resolution)

• Problem: Scheduled background jobs and cron reminders failed to deliver or sent alerts to wrong targets due to mismatched Discord channel/user recipient prefix parsing (channel:123 vs user:123).
• Solution: Fixed routing resolution logic in the agent gateway dispatcher to strictly validate target prefix tags, guaranteeing accurate notification delivery to either DM or designated channel targets.

4. False-Positive Test Reporting & Exit-Code Handling

• Problem: Automated developer runs reported test suite success when underlying test runners emitted errors or non-zero exit codes if stdout contained strings like "0 errors".
• Solution: Overhauled tool verification logic to bind test outcome evaluation strictly to process exit codes ($? / $LASTEXITCODE) and stderr inspection rather than string substring matching.

5. Long-Session Auto-Compaction Failures

• Problem: Running long-output tool commands (e.g., full test suites) inside a long-lived conversational session caused persistent "auto-compaction could not recover this turn" failures, even after increasing the compaction reserve buffer.
• Solution: Solved architecturally rather than by continuing to raise buffer limits — moved heavy or long-running tool work into isolated, short-lived scheduled agent sessions with lightweight context, keeping the main conversational session free of large tool output.

---

📂 Repository Structure

crestodian/
├── README.md                 # Project summary, architecture, case studies
├── ARCHITECTURE.md           # System topology, state management, safety boundaries
├── SECURITY.md               # Threat model, secret protection, safety guidelines
├── LICENSE                   # MIT License
├── .gitignore                # Environment, token, and memory ignore rules
├── skills/                   # Modular SKILL.md definitions
│   ├── reminders/
│   │   └── SKILL.md          # One-shot timers & cron reminder workflows
│   └── developer-daily/
│       └── SKILL.md          # Morning standup & repo status check workflows
├── config/                   # Example sanitized configuration files
│   ├── openclaw.example.json5# System configuration blueprint
│   └── TOOLS.example.md      # Tool declaration reference template
├── docs/                     # Detailed architectural & feature documentation
│   ├── design-decisions.md   # Architectural rationale and trade-offs
│   ├── setup.md              # Installation & configuration guide
│   ├── automation.md         # Timer, cron, and event automation docs
│   ├── developer-agent.md    # Autonomous coding & verification workflow
│   ├── google-workspace.md   # Gmail & Calendar read-only integration setup
│   └── future-integrations.md# Roadmap & planned features
└── examples/                 # Execution trajectories & log examples
    ├── reminder.md           # Sample reminder execution output
    ├── calendar-reminder.md  # Read-only calendar query & reminder trajectory
    ├── developer-daily.md    # Morning standup execution transcript
    └── controlled-bug-fix.md # Code patching & verification log

---

🗺️ Roadmap & Planned Features

• Local OpenClaw core agent gateway integration.
• Discord interface with streaming updates.
• Deterministic timer and cron scheduling.
• Google Workspace (Gmail & Calendar READ-ONLY via gog CLI) integration.
• Human-in-the-loop authorization gates for system commands.
• [PLANNED] Multi-Channel Discord Routing: Direct notifications to dedicated #alerts, #dev, or #calendar channels based on task tagging.
• [PLANNED] Vector-Based Memory Retrieval: Upgrade flat file context logs to local vector database embeddings (Chroma / LanceDB) for semantic long-term memory queries.
• [PLANNED] Automated PR Generation: Capability for the developer subagent to push topic branches and open GitHub Pull Requests directly.

---

⚡ Quick Start

1. Prerequisites: Node.js 18+, Python 3.10+, OpenClaw CLI, gog CLI, and a Discord Bot Token.
2. Setup Repository:

   git clone https://github.com/wajahat2005/crestodian.git
   cd crestodian

3. Configure Environment:
   • Copy config/openclaw.example.json5 to your local OpenClaw directory (~/.openclaw/openclaw.json5).
   • Follow the steps in docs/setup.md to set up API keys and Discord bot permissions.
4. Launch Agent:

   openclaw start --config ~/.openclaw/openclaw.json5

---

🛡️ License & Safety

This repository is distributed under the MIT License. Copyright (c) 2026 Wajahat.

For details on security boundaries, credential isolation, and reporting vulnerabilities, please consult SECURITY.md.