Introduction
You're talking to Hyperbot right now. It's my personal AI assistant that lives in my terminal, monitors my email, publishes blog posts, manages GitHub workflows, and can delegate complex coding tasks to external AI agents.
But I didn't build it from scratch. I started with Nanobot—an open-source modular AI assistant framework—and extended it to meet my specific workflow needs using Codex and iterative refinement.
Here's the journey from stock Nanobot to the fully-featured assistant running today.
What is Nanobot?
Nanobot is a modular AI assistant framework that provides:
- A tool execution layer (read/write files, shell commands, web search, email monitoring)
- A conversation interface (CLI with extensible channel support including Telegram)
- A skills system for reusable, composable workflows
- Memory management (session context + long-term storage + daily notes)
- Task-based model routing (different models for different task types)
It's designed to be extended—that's the whole point.
My Starting Point
When I first cloned Nanobot, it worked out of the box, but I needed it to integrate deeply with my daily development workflow:
- Email monitoring - Automated scanning of Gmail for job alerts, security updates, and important communications
- Better delegation - Robust handling of long-running coding tasks via external AI agents
- Custom skills - Skills for my infrastructure (blog publishing, Notion integration, GitHub workflows)
- GitHub integration - Deep integration with repos, PR reviews, and CI debugging
- Self-awareness - Ability to inspect and update its own source repository
- Model routing - Use different AI models for different tasks (chat vs email vs coding)
The Extension Process
Instead of writing all the extensions myself, I used Codex as a pair programmer:
The Process
- Define the requirement in clear, specific terms
- Show the codebase so Codex understands the patterns
- Iterate: Codex proposes code → I review → we refine → test
What Codex Helped Build
| Feature | What Codex Did |
|---|---|
| Email Monitor | Implemented IMAP-based scanning with account config, relevance filtering, and structured reports |
| Delegate Orchestrator | Created a PRD-first delegation system spawning Claude Code, Codex, OpenCode agents |
| Model Routing | Added persistent config for routing tasks to different models (default_chat, email, coding_plan) |
| Self-Repo Tool | Built GitHub CLI-based inspection and sync for hyperbot's own source |
| Skill System | Extended skills to support bundled scripts, dependencies, and availability checks |
| Cron Integration | Added scheduled reminders and recurring task management |
Hyperbot's Capabilities
After the extensions, Hyperbot now handles workflows that stock Nanobot couldn't:
🔍 Email Monitoring
- Scan multiple Gmail/IMAP accounts for unread emails
- Filter by relevance (jobs, security alerts, finance)
- Generate structured reports in Markdown and JSON
- Track scan history to avoid re-processing
- Time-scoped scans (today, all, custom ISO ranges)
🧠 Delegation System
- Spawn external coding agents (Claude Code, Codex, OpenCode) for complex tasks
- Monitor progress via transcript logs stored in
~/.hyperbot/state/delegate-logs/ - Enforce PRD-first workflow (no coding without clear objectives)
- Auto-reply to interactive prompts to prevent stalling
- Verify actual workspace file changes before claiming completion
🎯 Task-Based Model Routing
Persistent configuration allows different models for different contexts:
- default_chat: General conversations (currently GPT-4o)
- email: Email scanning and analysis
- coding_plan: Implementation planning for delegated tasks
This means you can use fast models for chat and more powerful models for complex reasoning—all automatically.
🛠️ Skills Library
The skill system now supports 14+ skills, each with bundled scripts and dependency management:
- Spreadsheet - Create/edit .xlsx, .csv, .tsv with openpyxl and pandas
- Playwright - Browser automation (navigation, forms, screenshots)
- Cron - Schedule reminders and recurring tasks
- GitHub - Interact with GitHub via gh CLI (issues, PRs, CI runs)
- Security Threat Model - Repository-grounded threat modeling with abuse paths
- Security Best Practices - Language-specific security reviews (Python, JS/TS, Go)
- Security Ownership Map - Git history analysis for security maintainership
- Notion Research - Synthesize info from multiple Notion sources into reports
- Notion Knowledge Capture - Turn chats into wiki entries with proper linking
- Notion Spec to Implementation - Convert PRDs into task plans with tracking
- Doc - Create/edit .docx documents with python-docx
- Cloudflare Deploy - Deploy apps to Workers and Pages
- GH Fix CI - Debug failing GitHub Actions checks
- GH Address Comments - Handle PR/issue review comments with gh CLI
- Bilawal.net Blog Post - This skill! Pulls blog repo, creates content, verifies build, pushes to GitHub
- Delegate Orchestrator - PRD-first coding with strict quality gates
📦 Memory Management
- Session memory - Current workspace, context, channel info
- Long-term memory - Important facts, user preferences, notes (persistent across sessions)
- Daily notes - Per-day journaling at
workspace/memory/YYYY-MM-DD.md - Cross-machine sync - Optional sync to
hyperflash-memoryrepo for audit trails
🔄 Self-Repository Management
- Status checks - Inspect git repo state, branch, and origin
- Auth setup - Configure GitHub CLI for non-interactive operations
- Sync workflow - Pull latest changes from upstream hyperbot repo
- Managed clones - Maintain clones under
workspace/repos/hyperbot
📱 Channel Support
- CLI - Primary interface via terminal
- Telegram - Mobile access with concise, mobile-optimized responses
- Extensible - Framework supports adding WhatsApp, Discord, and other channels
⏰ Scheduled Tasks
- One-shot reminders - Schedule specific-time notifications
- Recurring tasks - Cron-based scheduling for repeated actions
- Job management - List and remove scheduled tasks
The Architecture
Here's how it all fits together:
hyperbot/
├── nanobot/ # Nanobot core (conversation, tools)
├── skills/ # Reusable skill definitions (14+ skills)
│ ├── email-monitor/ # Gmail/IMAP scanning
│ ├── delegate-orchestrator/ # PRD-first coding delegation
│ ├── model-routing/ # Task-based model selection
│ └── bilawal.net-blog-post/ # Blog publishing skill
├── state/ # Runtime state (email DB, delegate logs, cron jobs)
├── workspace/ # Current working context
│ ├── memory/ # Long-term memory & daily notes
│ ├── reports/ # Generated reports
│ └── repos/ # Managed repository clones
└── config/ # Model routing preferences, account configs
Why This Approach Worked
Using Codex for extension had clear advantages:
- Speed - Features I'd estimate at days were implemented in hours
- Coherence - Codex understood Nanobot patterns and wrote consistent code
- Learning - The conversation taught me more about the codebase architecture
- Iterative refinement - Easy to say "change this" and see immediate diffs
It's not magic—there's still review, testing, and refinement required. But it's like having a very fast, very attentive junior developer who never gets tired of context switching and always follows your patterns.
What's Next?
I'm still extending Hyperbot. Current priorities:
- Better memory - More structured knowledge graph of preferences and context
- More channels - WhatsApp and Discord integration for multi-platform access
- Enhanced error handling - More graceful failures with clearer recovery paths
- Skill marketplace - Share and discover skills across the community
- Self-improvement - Hyperbot suggesting its own improvements based on usage patterns
Conclusion
Hyperbot exemplifies standing on the shoulders of giants. Nanobot provided the solid foundation, and Codex helped extend it into something personalized, useful, and continuously improving.
The lesson: You don't have to build everything from scratch. Find a good base project, understand it, then use AI to extend it for your needs. It's faster, you learn more, and you end up with something uniquely yours.