Building a Minimal Terminal Agent from Scratch: Core Mechanisms and Engineering Boundaries

1. What Problem Does a Terminal Agent Actually Solve?

AI-assisted programming has gone through roughly three stages.

The first stage was chat-based collaboration. Developers copied error logs, code snippets, and requirements into a chat window; the model analyzed the problem and offered suggestions; then the developer manually changed local files and reran the program. This stage lowered the cost of looking up information and locating problems, but the actual execution still depended on humans.

The second stage was in-editor assistance. The model could generate code for the current file, complete functions, and explain errors, so developers did not have to switch windows as often. However, these capabilities usually still revolved around the current editing position. The model did not automatically inspect the whole project state, nor did it continuously observe command execution results.

The third stage is the terminal agent. The user only needs to describe a goal, for example:

Locate the cause of test failures in the project, fix the relevant code, rerun the tests, and summarize the changes.

The agent can then follow a process such as:

1. Inspect the project directory;
2. Search for relevant functions, configuration, or test files;
3. Read the necessary code snippets;
4. Analyze error messages;
5. Modify files;
6. Run tests or build commands;
7. Continue fixing based on the new output;
8. Summarize the changes when finished.

The key here is not that the model suddenly gains “autonomous consciousness.” Instead, the system connects the model’s text reasoning ability with a set of controlled tools. The model decides the next step, the program performs the actual execution, and the execution result is fed back to the model, forming a bounded loop.

Therefore, the basic structure of an agent can be abstracted as:

User goal
   ↓
Model analysis
   ↓
Generate tool call
   ↓
Local tool execution
   ↓
Return execution result
   ↓
Model continues to decide

This is also the first principle for understanding terminal agents: it is not a mysterious black box, but a combined system of “model + tools + state management + safety boundaries.”

2. Why Minimal Example Code Is Hard to Use Directly in Real Projects

Many introductory examples only need to do three things: call the model, parse the response, and execute a command. Such code helps explain the concept, but it is difficult to use directly in a real development environment.

1. Child Processes May Block Indefinitely

The simplest way to execute a command is usually to wait for the child process to finish and then read the output all at once:

import subprocess
result = subprocess.run(
    command,
    shell=True,
    capture_output=True,
    text=True
)

This approach works for short commands, but the following situations may cause the program to hang for a long time:

• The command waits for user input;
• The child process starts an interactive program;
• The child process creates a new background process;
• The standard output buffer is filled;
• The build task itself takes a long time;
• The child process enters an infinite loop or waits for a lock.

Therefore, a production-grade implementation needs at least timeout handling, real-time output, process termination, and exit-status checking.

2. Unbounded File Reads Can Overwhelm the Context

Logs, dependency directories, generated files, and large data files in a project can all be very large. If the agent sends complete files to the model every time, it not only increases call cost but quickly exhausts the context window.

A more reasonable approach is to:

• Read only a limited number of lines by default;
• Search first, then read content near the match;
• Compress repeated content;
• Slice logs by time or error level;
• Provide summaries for large files instead of full text;
• Set a maximum output length for each tool call.

The context window can be compared to a desk of limited size. Only the most important books and tools for the current task can fit on the desk. If you dump out the entire backpack, the content you actually need may be buried.

3. The Model May Generate Dangerous Commands

Once a terminal agent has execution capability, the risk increases significantly. Operations such as deleting files, overwriting configuration, changing permissions, and uploading sensitive information cannot simply be approved based on the model’s judgment.

Therefore, the system should at least distinguish three types of operations:

• Read-only operations: listing directories, searching text, reading files;
• Reversible modifications: editing code, generating temporary files;
• High-risk operations: deleting files, changing permissions, accessing external services, executing unknown scripts.

High-risk operations should require human confirmation or run in an isolated directory. Permission control cannot rely on the model’s self-discipline; it must be enforced by the host program.

3. Minimal Viable Architecture: Four Core Modules

A terminal agent that does not depend on a complex framework can be divided into four modules.

1. Model Adapter Layer

The model adapter layer is responsible for only two things:

• Sending the conversation history to the model;
• Obtaining the model’s returned text or structured tool calls.

To avoid coupling business logic with a specific model interface, define a unified method:

class ModelClient:
    def ask(self, messages):
        """
        Accept a message list and return the model response.
        In a real project, HTTP requests, authentication, and retries can be wrapped here.
        """
        raise NotImplementedError

In this way, the tool system, context management, and main loop do not need to care about the underlying call details.

2. Tool Registration Layer

Tools should not be scattered directly throughout the main program. Instead, they should be registered using a unified description:

TOOLS = {
    "list_files": {
        "description": "List files in the specified directory",
        "handler": list_files,
    },
    "read_file": {
        "description": "Read a limited amount of file content",
        "handler": read_file,
    },
    "run_command": {
        "description": "Execute a controlled command and return output",
        "handler": run_command,
    },
}

The model can only call registered tools and cannot execute arbitrary Python code out of thin air. Each tool should also clearly define its input format, output format, and risk level.

3. Context Management Layer

The context manager controls the number of messages and the size of their content. A practical strategy is to set a character limit for each message:

def truncate(text, limit=12000):
    if len(text) <= limit:
        return text
    head = limit * 2 // 3
    tail = limit - head
    return text[:head] + "\n...[content truncated]...\n" + text[-tail:]

However, simple truncation is not always enough. A better approach is to preserve:

• The user’s original task;
• The most recent tool calls;
• The latest failure information;
• The list of files currently modified;
• Confirmed constraints.

Older detailed output can be compressed into summaries so that the full history is not carried in every round.

4. Agent Main Loop

The main loop drives the task forward:

def agent_loop(goal, model, tools, max_rounds=12):
    messages = [
        {"role": "system", "content": "You are a controlled terminal development assistant."},
        {"role": "user", "content": goal},
    ]
    for _ in range(max_rounds):
        response = model.ask(messages)
        if response.get("type") == "final":
            return response.get("content", "")
        if response.get("type") != "tool_call":
            messages.append({
                "role": "assistant",
                "content": response.get("content", "")
            })
            continue
        name = response["name"]
        arguments = response.get("arguments", {})
        if name not in tools:
            result = "Error: unregistered tool"
        else:
            try:
                result = tools[name]["handler"](**arguments)
            except Exception as exc:
                result = f"Tool execution exception: {exc}"
        messages.append({"role": "assistant", "content": str(response)})
        messages.append({
            "role": "tool",
            "content": truncate(str(result))
        })
    return "Task reached the maximum number of rounds and has stopped."

The max_rounds value is very important. An agent without a limit may repeatedly try the same failing action, wasting time and resources.

4. Terminal Executor: Managing Commands Matters More Than Launching Them

1. Basic Safety Checks

Before executing a command, the working directory and command risk should be checked first:

import os
import subprocess
DANGEROUS_WORDS = [
    "format",
    "shutdown",
    "reboot",
    "chmod 777",
]
def run_command(command, cwd=None, timeout=30):
    cwd = cwd or os.getcwd()
    lowered = command.lower()
    for word in DANGEROUS_WORDS:
        if word in lowered:
            return f"Command blocked: contains a high-risk operation: {word}"
    try:
        process = subprocess.Popen(
            command,
            cwd=cwd,
            shell=True,
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
            text=True,
            bufsize=1
        )
        lines = []
        try:
            for line in process.stdout:
                lines.append(line)
                if sum(len(x) for x in lines) > 20000:
                    lines.append("\n...[output limit exceeded]...")
                    process.kill()
                    break
        except Exception:
            process.kill()
            raise
        process.wait(timeout=timeout)
        output = "".join(lines)
        return f"Exit code: {process.returncode}\n{output}"
    except subprocess.TimeoutExpired:
        process.kill()
        return "Command timed out; process terminated"
    except Exception as exc:
        return f"Command execution failed: {exc}"

This code is still only a minimal implementation. A real scenario also needs to handle process groups, child-process cleanup, encoding exceptions, and operating system differences. But it already demonstrates several key principles: output limits, execution timeouts, risk blocking, and explicit return of the exit status.

2. Why a Pseudo-Terminal Is Needed

Some programs flush output only when connected to a real terminal, or change their behavior based on the terminal environment. Ordinary pipes are suitable for batch reading of output, but they cannot fully simulate an interactive terminal.

A pseudo-terminal can be understood as a “fake terminal device”: the agent sends input to the program through it while reading the program’s output in real time. For tasks that require interaction, a pseudo-terminal can improve:

• Real-time log display;
• Handling of interactive prompts;
• Compatibility with colored output;
• Program recognition of the terminal environment;
• Status observation for long-running tasks.

However, pseudo-terminals are not implemented in exactly the same way across operating systems. Therefore, a cross-platform solution should abstract the terminal layer into a unified interface and adapt it separately on different systems. It should not assume that one underlying mechanism works in every environment.

5. File Tool Design: Prefer Precise Reads over Blind Reads

The most basic file tools usually include directory listing, text search, partial reading, and controlled writing.

from pathlib import Path
def safe_path(root, user_path):
    root = Path(root).resolve()
    target = (root / user_path).resolve()
    if root != target and root not in target.parents:
        raise ValueError("Path is outside the working directory")
    return target
def read_file(root, filename, start=1, end=200):
    path = safe_path(root, filename)
    with path.open("r", encoding="utf-8", errors="replace") as f:
        lines = f.readlines()
    start = max(1, start)
    end = min(len(lines), end)
    selected = lines[start - 1:end]
    return "".join(
        f"{index}: {line}"
        for index, line in enumerate(selected, start=start)
    )

The most important part here is the path constraint. A user may ask the agent to read a file, but the path generated by the model is not necessarily reliable. Without restricting the working directory, the agent could access sensitive system files or content outside the project.

When writing files, direct overwriting of the original file should also be avoided. A temporary file plus atomic replacement can be used:

1. Write the new content to a temporary file;
2. Verify that the file was written successfully;
3. Keep a backup of the old file;
4. Use atomic replacement to update the target file.

In this way, even if the program fails midway, it is less likely to leave a half-written file.

6. The ReAct Loop Is a Bounded Closed Loop, Not Endless Trial and Error

A common way for terminal agents to work can be summarized as:

Observe: obtain directories, code, or error logs
Think: determine the cause and next action
Act: call read, edit, or execution tools
Feedback: read the execution result

But an engineering implementation cannot simply let the model repeat this process forever. The following constraints are recommended.

1. Maximum Number of Rounds

For example, execute at most ten to fifteen rounds. After exceeding the limit, output the current state and the reason the task is incomplete.

2. Repeated Action Detection

If exactly the same command is executed for several consecutive rounds and the result does not change, stop immediately and alert the user.

3. Modification Scope Limit

Record the files modified during the current task. If the model suddenly tries to modify a large number of unrelated files, pause and request confirmation.

4. Test First

After modifying code, run the smallest relevant test set first, then gradually expand the scope. This reduces meaningless long builds.

5. Failure Classification

Classify failures into:

• Command not found;
• Insufficient permissions;
• Syntax error;
• Test assertion failure;
• Missing environment dependency;
• Timeout or insufficient resources.

Different types of errors require different handling. They cannot all be reduced to “try again.”

7. Human Interaction and Automated Configuration Should Coexist

A practical terminal agent usually supports two working modes.

Human Confirmation Mode

Whenever file modification, command execution, or a high-risk operation is involved, show the following first:

Upcoming action:
Command: run project tests
Directory: current working directory
Risk: may create temporary files
Continue? [y/N]

This mode is suitable for production environments, unfamiliar projects, and important codebases.

Declarative Automatic Mode

In controlled directories, continuous integration, or batch tasks, allowed operations can be declared through a configuration file:

{
  "workspace": "./demo",
  "allow_read": true,
  "allow_write": true,
  "allow_commands": ["test", "build"],
  "max_rounds": 10,
  "command_timeout": 60
}

The value of declarative configuration is that permissions become auditable and reproducible, rather than depending on one-off interactive choices.

8. What Else Is Needed to Move from a Local Script to a Production System?

To extend a tiny agent into an engineering system usable by a team, the following should also be added:

1. Logging and auditing: record user goals, tool calls, command output, and file changes;
2. Secret isolation: prevent the model from directly reading sensitive credentials in environment variables;
3. Sandbox execution: run commands in an isolated directory, container, or restricted user account;
4. Change rollback: create a patch for each modification and support one-click undo;
5. Resource limits: limit CPU, memory, disk, network, and execution time;
6. Structured protocols: use explicit data structures for tool calls and avoid relying on fuzzy text parsing;
7. Observability: track per-round latency, failure reasons, tool usage counts, and context size;
8. Human takeover: when the model cannot decide, it should actively pause rather than continue guessing.

Conclusion

The core of a terminal agent is not stacking complex frameworks, nor is it giving the model unlimited permissions. What really determines system quality is tool boundaries, execution safety, context control, error recovery, and task closure.

The most valuable takeaway from implementing a minimal Agent CLI from scratch is not a piece of example code to show off. It is understanding how the whole system works: the model proposes actions, tools execute them, the environment returns facts, the state manager filters information, the safety layer limits risk, and the main loop advances the task within a finite number of rounds.

Once these mechanisms are separated, the so-called “agent” is no longer mysterious. It is essentially an observable, constrained, and recoverable software engineering system. Whether you connect local models, enterprise model services, or general model capabilities such as Baidu AI Cloud, the underlying engineering principles remain the same: let the model do the reasoning it is good at, let the program handle reliable execution, and keep final control in human hands.