NIMBL — Devlog #1: Building a Token-Efficient CLI Companion

I started NIMBL because I wanted a coding assistant that lives in the terminal and actually conserves tokens instead of burning through context windows. The goal for this first phase was to build a lightweight, responsive tool with a polished feel without unnecessary bloat.

Adapting OpenCode’s TUI Architecture

My initial approach was building a terminal interface from scratch using standard Textual widgets. I got a basic mockup working, but the component architecture felt rigid and didn’t scale well. Instead of continuing with a fragile layout, I pulled down the OpenCode CLI source code (anomalyco/opencode), studied its TUI architecture, and adapted its two-column layout system for NIMBL.

Decoupled Components: Refactored the app into a persistent sidebar (housing the model selector and session history), a main chat panel, and a live status bar.
Theme & Identity: Extracted the CSS structure into styles.tcss. I kept the dark background (#0a0a0a) but shifted the accent color from orange to a custom green (#4ade80) to give NIMBL its own identity.

Multi-Provider Backend & Failover

The backend is where the core engineering happened. I built a multi-provider API client that speaks OpenAI-compatible endpoints across Hack Club AI, Google AI Studio, Groq, and local Ollama.

Automatic Failover: If an active provider drops or hits a rate limit, the client automatically rotates to the next available provider without interrupting the session.
Streaming & Telemetry: Responses stream directly into the chat panel in real-time, with token usage tracked on every API call to keep resource consumption visible.

Context Budget Allocator & /compact

To keep context usage strictly governed, I built a context engine driven by a token budget allocator. Instead of letting prompts grow infinitely, the context window is portioned into fixed allocations:

15% System Prompts: Reserved for base instructions and active mode constraints.
25% Retrieved Context: Allocated for project structure, active files, and RAG retrieval.
35% Conversation History: Dedicated to the active chat thread.
Scratchpad Space: The remaining allocation is preserved for scratch work and generation.

The system automatically warns you when reaching 60% capacity and provides a /compact command to summarize and prune older messages.

Modes, Gamification, and CLI

NIMBL features three operational modes, each with its own system prompt and context state:

Assist Mode: A direct coding partner focused on concise, minimal code suggestions.
Learn Mode: A Socratic tutor that guides you through concepts using progressive hints rather than giving answers immediately.
Review Mode: A teaching code reviewer that explains why code is problematic rather than just flagging syntax.

I also integrated a learning tracker that records XP, streaks, and skill mastery as you work through concepts, alongside a prompt cache layer that estimates savings from repeated system prefixes.

Everything is wrapped in Click commands: nimbl run launches the TUI, nimbl ask handles one-shot terminal queries, and nimbl setup walks through API key configuration.

Next Steps

UI Event Integration: Wire TUI message events (MessageSubmitted) directly to the backend agent logic.
Telemetry Refinement: Connect the status bar directly to real-time token metrics.
Local File Tooling: Implement tools to let the agent read and write files.