Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

This paper introduces OPENDEV, an open-source, terminal-native AI coding agent that ensures secure and efficient autonomous software engineering through a compound architecture featuring specialized model routing, a dual-agent planning-execution separation, adaptive context compaction, and an automated memory system to counteract instruction fade-out.

The Gist

Imagine you have a brilliant, hyper-intelligent assistant who knows how to code better than anyone else. But there's a catch: this assistant has a very short attention span (a "limited memory"), gets easily distracted, and if you let them loose on your computer without supervision, they might accidentally delete your entire hard drive.

OPENDEV is a new, open-source project designed to solve these problems. It's a "terminal-native" AI agent, meaning it lives in your command line (the black screen where developers type commands) rather than inside a fancy visual editor.

Here is the story of how OPENDEV works, explained through simple analogies.

1. The Problem: The "Amnesiac" Genius

Most AI coding tools today are like a genius student who can solve a math problem instantly but forgets the first step of the problem by the time they reach the tenth step. If you ask them to build a complex app, they might start well, but after 20 steps, they forget what the goal was, get confused by the massive amount of text they've read, or accidentally run a command that deletes your files.

OPENDEV was built to fix three main issues:

• Memory: It can't remember everything forever.
• Safety: It can't be trusted to do anything without a safety net.
• Focus: It tends to rush into action instead of thinking.

2. The Solution: The "Swiss Army Knife" Factory

Instead of relying on one giant brain to do everything, OPENDEV is built like a well-organized factory with different specialized workers.

The "Scaffolding" (The Blueprint)

Before the AI even sees your first question, the system builds a custom team for you. It's like a construction site manager who sets up the tools, hires the right specialists, and draws the safety lines before the work starts.

• The Main Agent: The project manager.
• The Sub-Agents: Specialized workers. One is a "Code Explorer" (just looks at code, never touches it), another is a "Planner" (draws the blueprint), and another is a "Security Reviewer."
• The Magic: If you need a web developer, the system hires a web specialist. If you need a database expert, it hires that person. They all speak the same language but have different toolkits.

The "Harness" (The Safety Harness)

Once the team is built, the "Harness" takes over. This is the runtime system that keeps everything running smoothly and safely.

• The "Thinking" Phase: Before the AI is allowed to touch your code, it is forced to take a "thinking break." It's like a chef who must write down the recipe and check the ingredients before turning on the stove. This prevents the AI from rushing and making mistakes.
• The "Self-Critique" Phase: After thinking, the AI asks itself, "Did I miss anything?" It's like a second pair of eyes reviewing the plan before execution.

3. The "Memory" Problem: The Filing Cabinet vs. The Trash Can

The biggest challenge for AI is that its "context window" (its working memory) is limited. Imagine trying to read a 500-page book, but you can only hold 5 pages in your hands at a time. As you read, you have to put pages down.

OPENDEV uses a clever system called Adaptive Context Compaction:

• The "Faded" Files: When the AI reads a file 20 minutes ago, the system doesn't throw it away. Instead, it replaces the full text with a tiny note: "Read 'database.py' earlier. It had 50 lines. We discussed the login function." This saves space.
• The "Scratch Pad": If a command produces a huge log (like 10,000 lines of error messages), the AI doesn't stuff all of it into its memory. It writes the full log to a temporary file on your hard drive and just keeps a note saying, "The log is saved in file X. Read it if you need details."
• The "Reminders": As the conversation gets long, the AI starts to forget the rules (like "always run tests after editing"). OPENDEV acts like a helpful coach who whispers, "Hey, don't forget to run the tests!" right at the moment the AI is about to move on.

4. The Safety Net: The "Five-Layer" Castle

Since the AI can run commands that delete files, OPENDEV doesn't just say "Please be nice." It builds a fortress with five layers of defense:

1. The Rulebook (Prompt): The AI is told, "You are a helpful assistant, not a hacker."
2. The Tool Chest (Schema): The AI is literally not given the keys to dangerous tools unless it's in "Plan Mode." If the tool doesn't exist in its list, it can't use it.
3. The Gatekeeper (Approval): For dangerous actions (like deleting a file), the system stops and asks you: "Are you sure?"
4. The Inspector (Validation): Before a command runs, the system checks, "Is this command trying to delete the whole hard drive? If yes, block it."
5. The Undo Button (Persistence): If the AI makes a mistake, you can hit "Undo," and the system uses a hidden "time machine" (a shadow git repository) to restore your files exactly how they were before.

5. The "Lazy" Discovery

Imagine you have a library with 10,000 books. If you ask the AI to "read the library," it would take forever and waste time.
OPENDEV is lazy in a good way. It doesn't load all 10,000 books into its brain at startup. It only loads the "Table of Contents." When you ask, "How do I connect to a database?", then it goes and fetches the specific "Database" book. This keeps the AI fast and focused.

The Big Picture

OPENDEV is a blueprint for how to build AI that is safe, smart, and actually useful for real-world software engineering.

Instead of a "magic black box" that sometimes works and sometimes deletes your data, OPENDEV is a structured, transparent, and safe environment. It treats the AI like a brilliant but clumsy intern:

• Give them a clear plan.
• Let them think before they act.
• Give them specialized tools.
• Watch them closely with safety nets.
• And always, always have an "Undo" button ready.

It's not just about writing code; it's about building a system where humans and AI can work together without the AI accidentally burning down the house.

Technical Summary

Based on the paper "Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned", here is a detailed technical summary of the OPENDEV system.

1. Problem Statement

The landscape of AI coding assistance is shifting from IDE-integrated plugins to terminal-native agents. While Large Language Models (LLMs) have shown promise in autonomous software engineering, existing systems face three fundamental engineering challenges when operating in long-running terminal sessions:

• Context Bloat: Tool outputs (file contents, command logs) rapidly consume finite token budgets, leading to "context rot" where the model forgets initial instructions or goals.
• Safety Risks: Agents executing arbitrary shell commands pose a risk of destructive operations (e.g., deleting files, breaking builds) if safety mechanisms are not robust.
• Instruction Fade-out: As conversations lengthen, the model's attention drifts away from initial system prompts, leading to premature task completion or failure to recover from errors.
• Lack of Open Technical Reports: Most production-grade CLI agents are closed-source (e.g., Claude Code) or lack comprehensive technical documentation, leaving a gap in understanding how to engineer robust, open-source agentic systems.

2. Methodology: The OPENDEV Architecture

OPENDEV is an open-source, command-line coding agent designed as a Compound AI System. Instead of relying on a single monolithic LLM, it employs a structured ensemble of agents, workflows, and tools. The architecture is organized into four layers:

A. Agent Core (Scaffolding & Harness)

• Scaffolding (Pre-runtime): Agents are fully assembled before the first prompt. This includes compiling system prompts, building tool schemas, and registering subagents. This "eager construction" eliminates first-call latency and ensures agents are ready immediately.
• The Harness (Runtime): A runtime orchestration layer that wraps the reasoning loop. It manages tool dispatch, context compaction, safety enforcement, and session persistence.
• Dual-Mode Operation:
  • Plan Mode: Delegates to a specialized Planner Subagent with read-only tools. It explores the codebase and generates a structured plan without the ability to write files, preventing accidental changes during the design phase.
  • Normal Mode: The main agent executes the plan with full read-write access.
• Extended ReAct Loop: The reasoning cycle is expanded beyond standard Reason-Act to include:
  1. Context Management: Staged compaction before every turn.
  2. Thinking Phase: An optional, tool-free reasoning step to encourage deep deliberation before action.
  3. Self-Critique: A review phase for complex tasks.
  4. Action/Execution: Standard tool invocation.

B. Context Engineering Layer

OPENDEV treats context management as a first-class engineering concern to prevent token exhaustion:

• Adaptive Context Compaction (ACC): Instead of a binary emergency trigger, ACC uses a five-stage pipeline (Warning → Observation Masking → Fast Pruning → Aggressive Masking → Full Summarization) based on token pressure (70%–99%).
• Dual-Memory Architecture: Separates Episodic Memory (compressed summary of the full history) from Working Memory (verbatim recent exchanges) to maintain strategic goals while preserving operational details.
• Event-Driven System Reminders: To counteract instruction fade-out, the system injects short, targeted "user-role" reminders at the point of decision (e.g., when a task is incomplete or an error occurs) rather than relying solely on the initial system prompt.
• Tool Result Optimization: Raw tool outputs are summarized or offloaded to scratch files if they exceed size thresholds, replacing verbose logs with compact metadata in the context window.

C. Tool System & Safety

• Registry-Based Architecture: Tools are organized into categories with lazy discovery via the Model Context Protocol (MCP). Only relevant tool schemas are loaded into the context, saving tokens.
• Defense-in-Depth Safety: A five-layer safety architecture ensures no single point of failure:
  1. Prompt-Level: Behavioral guardrails.
  2. Schema-Level: Removing write tools from the Planner subagent's schema (structural impossibility of writing).
  3. Runtime Approval: User confirmation for dangerous commands.
  4. Tool-Level Validation: Blocking dangerous patterns (e.g., rm -rf) and detecting stale reads.
  5. Lifecycle Hooks: External scripts to intercept and modify tool arguments.
• Fuzzy Matching: The edit_file tool uses a 9-pass chain-of-responsibility matcher to handle LLM formatting drift (whitespace, indentation), converting near-misses into successful edits.

D. Persistence & Configuration

• Session Management: Conversations are stored as JSON/JSONL files with an auto-generated index for fast retrieval.
• Shadow Git Snapshots: For every file modification, a "shadow" Git repository captures the state, enabling a single-command undo that restores files to their pre-agent state, even for uncommitted changes.
• Multi-Model Routing: Different cognitive tasks (planning, execution, thinking, summarization) can be routed to different LLMs (e.g., a cheap model for summarization, a powerful one for reasoning) via user configuration.

3. Key Contributions

1. Per-Workflow LLM Configurability: A compound architecture where different cognitive phases (thinking, acting, critiquing) bind to independent, user-configured LLMs, optimizing cost and latency.
2. Extended ReAct Pipeline: Integration of explicit thinking and self-critique phases, along with staged context compaction directly into the reasoning loop.
3. Behavioral Steering Mechanisms: Event-driven system reminders and a conditional prompt composition pipeline that injects guidance exactly when needed, combating attention decay.
4. Token-Efficient Extensibility: Lazy tool discovery via MCP and a registry-based tool system that minimizes context overhead.
5. Comprehensive Safety & Undo: A five-layer safety architecture and a shadow Git-based undo system that allows for safe, reversible agent operations.

4. Results & Performance

While the paper focuses on architectural design rather than benchmark scores, it reports significant engineering outcomes:

• Context Efficiency: Adaptive Context Compaction reduces peak context consumption of observations by approximately 54%, often eliminating the need for emergency summarization in 30-turn sessions.
• Latency & Cost: Lazy tool discovery reduced baseline context overhead from ~40% (loading all schemas) to <5%.
• Reliability: The dual-memory architecture and system reminders resolved failure modes where agents previously "forgot" goals or instructions after 20+ tool calls.
• Error Recovery: Classifying errors and injecting targeted recovery templates improved recovery rates compared to generic "try again" prompts.

5. Significance

OPENDEV represents a blueprint for robust autonomous software engineering in the terminal. Its significance lies in:

• Bridging the Gap: It provides the first comprehensive technical report for an open-source, production-ready, terminal-native coding agent, demystifying the design decisions behind closed-source competitors.
• Engineering over Algorithms: The paper argues that the primary challenges in agentic coding are not algorithmic but engineering challenges (context management, safety, tool orchestration).
• Scalability & Safety: By demonstrating how to manage finite context windows and enforce safety through architectural constraints (schema gating) rather than just runtime checks, it offers a viable path for deploying long-horizon autonomous agents in real-world development environments.
• Open Source Foundation: It establishes a modular, extensible foundation for the community to build upon, moving beyond benchmark-oriented frameworks to interactive, daily-use tools.

In summary, OPENDEV demonstrates that effective terminal agents require a shift from "prompt engineering" to system engineering, prioritizing context efficiency, safety layers, and adaptive memory management to sustain autonomous operation over long development cycles.