$ show synthetic-lab/octofriend
This repository contains Octo (Octofriend), a terminal-native AI coding assistant that integrates with numerous LLM providers (OpenAI, Anthropic, Codex, and any OpenAI-compatible API) to offer an interactive agentic coding experience. The application is built entirely in TypeScript using Bun as the runtime and a custom Rust-based terminal rendering engine ('paintcannon') along with a React-like component library. It provides a rich set of tools for the AI agent, including file operations (read, edit, create, rewrite, partial read), shell command execution, glob/grep/search, web search via SearXNG, LSP integrations (definitions, references, hover, diagnostics, etc.), MCP server support, and a skill system. The application manages complex session state with a Zustand store, persists history in SQLite via Drizzle ORM, and supports configurable authentication (API keys, OAuth for Codex, shell commands). It also features an autofix mechanism using small specialized models (diff-apply, fix-json) that are trained with synthetic data generation pipelines included in the repository. The architecture follows a modular, compiler-based pattern: the core agent loop in `trajectory-arc.ts` orchestrates LLM calls through a compiler interface that abstracts across different providers. The system uses a custom Intermediate Representation (IR) for conversations, enabling subagent trajectories, context summarization ('autocompact'), and efficient session serialization. The UI is rendered as a state machine driven by an interactive mode system, handling transitions for responding, tool-call confirmation, error recovery, and compacting. The codebase also includes a substantial training pipeline for autofix models, generating synthetic broken JSON and diff-edit examples from git history, and training small LoRA models using the 'unfat' library. While primarily an application, this hybrid nature adds research depth to the project's data engineering components. The repository demonstrates high software craftsmanship with clean abstractions like a Result/Option monad pattern, a declarative ToolBuilder for tool definitions, a generic compiler interface, and a well-tested OctoProcessManager for safe child process lifecycle management. The codebase is actively maintained with frequent commits, thorough compile-time assertions, and a comprehensive test suite. It does suffer from some monolithism in the main UI file and tight coupling to a few private packages, but overall it represents a production-grade, extensible AI assistant platform.
The LLM identified 6 files worth highlighting for reuse:
Provides a generic Result/Option type (ok/err, some/none) with utility functions like flatten, unwrap, map, bind, and cata. This pattern is used pervasively throughout the codebase for explicit error handling, avoiding exceptions. It is a self-contained module with no internal dependencies, easily extractable to any TypeScript project that needs railway-oriented programming.
Defines a ToolBuilder DSL for declaring AI tool specifications with typed schemas, custom intermediate representations (IR), and automatic argument parsing/validation. The builder pattern enables a clean declaration of tool name, description, parameters (using structural library for JSON schema), and a run handler. This module is reusable in any project that needs to define typed, validated tools for LLM interactions.
Defines the Compiler interface and helper types (CompilerResult, CompilerUsage, compilerModalities) that abstract over different LLM providers. The defineCompiler factory function standardizes compiler creation with built-in streaming support. This pattern allows easy addition of new LLM backends (standard OpenAI, OpenAI Responses, Anthropic, Codex) without changing the agent loop, making it a reusable integration layer for any multi-provider LLM system.
Implements OctoProcessManager that wraps child processes with safe lifecycle management: cleanup on exit, signal handling, group termination, and double-ctrl-c handling. It enforces a single-instance pattern and provides global signal handler installation. This module is self-contained and can be extracted to any Node.js/Bun application requiring robust child process management with graceful termination.
Implements an automatic context compaction strategy: when the conversation exceeds a token threshold, it invokes the same LLM with a structured prompt to generate an <analysis> and <summary> tag, then replaces the prior conversation with the summary. This is a reusable pattern for any context-sensitive LLM application that needs to manage token limits without losing valuable conversation context.
Defines the Transport interface abstracting file system operations and shell command execution. Implementations include local and Docker transports, and a fake transport for testing (used in read.test.ts). This pattern enables the tool system to operate transparently in different environments and is reusable for any project that needs to decouple file/shell operations from business logic.