ArchonCLI

ArchonCLI: Gemini 3-powered autonomous AI code architect. Uses Tree-Sitter & RAG for deep codebase insights via modern TUI or scriptable CLI.

Comment

ArchonCLI: The Autonomous AI Code Architect 🏛️

Inspiration

We noticed a critical gap in the current landscape of AI coding assistants. While browser-based chatbots are great for snippets, they suffer from "Semantic Fragmentation" and "Dependency Blindness" when dealing with large, complex codebases. They treat code as plain text, often missing the architectural glue that holds a project together.

We wanted to build something different: a tool that doesn't just "autocomplete" code, but understands architecture. We were inspired to create a developer companion that lives where developers live—the terminal—and possesses the deep reasoning capabilities of a Senior Architect, powered by the next generation of Google Gemini.

What it does

ArchonCLI is an autonomous, AI-powered architect assistant designed to master complex codebases. It serves as a "second brain" for developers, offering:

  • 🧠 Deep Semantic Understanding: It doesn't just read files; it understands functions, classes, and types using Syntax-Aware RAG.
  • 💬 Interactive TUI: A beautiful, modern terminal interface for chatting with your codebase without leaving your workflow.
  • 🛠️ Developer Power Tools: Automates tedious tasks with commands like:
    • archon review: AI-driven code reviews for staged changes.
    • archon commit: Generates semantic commit messages instantly.
    • archon test: Writes unit tests for specific functions.
    • archon diagram: Generates Mermaid/PlantUML architecture diagrams.
  • ⚡ Smart Caching: Remembers previous contexts to answer faster and cheaper.

How we built it

We engineered ArchonCLI with a focus on performance, portability, and "Pure Go" architecture:

  1. Core Engine (Go): We chose Go (Golang) for its concurrency and ability to compile into a single, static binary with zero external dependencies.
  2. The Brain (Google Gemini 3): We leveraged Gemini 3 Pro for deep reasoning and Flash for high-speed embeddings. We heavily utilized Context Caching to maintain state across interactions.
  3. The Eyes (Tree-Sitter): Instead of naive text chunking, we used Tree-Sitter to parse code into Abstract Syntax Trees (AST), ensuring the AI understands the structure of the code.
  4. The Memory (Chromem-go): We implemented a local, embedded vector database using chromem-go, eliminating the need for heavy external vector DBs like Pinecone or Qdrant.
  5. The Face (Bubble Tea): We built a rich TUI using the Charm ecosystem (Bubble Tea, Lip Gloss) to bring a modern UI experience to the CLI.

Challenges we ran into

  • Handling API Rate Limits: Indexing a large codebase requires thousands of embedding requests. We had to implement a robust Token Bucket algorithm to maximize throughput without triggering Google's API rate limits.
  • Pure Go Vector Search: finding a performant vector database that could run embedded within the Go binary (without CGO or external servers) was difficult. Integrating chromem-go allowed us to keep the tool portable.
  • Context Window Management: Feeding an entire codebase into an LLM is impossible. Balancing "retrieval precision" (finding the right code) with "context window limits" required fine-tuning our RAG pipeline to be syntax-aware.

Accomplishments that we're proud of

  • 🚀 90% Cost & Latency Reduction: By successfully implementing Gemini Context Caching, we drastically reduced the overhead for follow-up queries.
  • 📦 Zero-Dependency Binary: We achieved our goal of a single executable file. No Python environment, no Docker containers, no node_modules—just one binary that works on Windows, macOS, and Linux.
  • ✨ The TUI Experience: We're incredibly proud of the terminal interface. It feels polished, responsive, and proves that CLI tools don't have to be ugly or hard to use.

What we learned

  • Syntax Matters: RAG for code is fundamentally different from RAG for text. "Chunking by function" yields significantly better results than "chunking by paragraph."
  • The Power of Caching: LLMs are stateless by default, but stateful caching changes the game for conversational coding assistants.
  • Go is Great for AI Engineering: While Python dominates AI research, Go is the superior choice for building high-performance, distributable AI infrastructure tools.

What's next for ArchonCLI

  • 🔌 LSP Integration: We are currently working on a Language Server Protocol (LSP) implementation (already in the codebase!) to bring Archon directly into VS Code and Neovim as a native plugin.
  • agentic Workflows: Moving beyond "Ask" to "Act"—allowing ArchonCLI to autonomously refactor code across multiple files based on a high-level architectural plan.
  • Team Knowledge Graph: synchronizing embeddings across a team so that every developer shares the same "brain" regarding the project's architecture.

Built With

  • bubbletea
  • chromem-go
  • cobra
  • gemini-3
  • generative-ai
  • go
  • google-cloud
  • google-gemini
  • llm
  • rag
  • tree-sitter
  • vector-database
Share this project:

Updates