TermAgent v2

A terminal-based AI agent that executes system tasks using natural language. Talk to your terminal using ?? prefix.

📖 Full Tutorial — Installation, usage, multi-turn conversations, contextual references, and how to add custom modules.

Demo

$ pwd
/home/user

$ ?? listame esta carpeta
=== /home/user ===
Documents/
Downloads/
Projects/

$ ?? crear carpeta test
Folder 'test' created

$ ?? copiar go.mod a test
Copied 1 items to '/home/user/test'

$ ?? crear carpeta alpha en C:\temp, copiar go.mod a alpha, listar C:\temp
[1] create (OK):
Folder 'alpha' created in 'C:/temp'

[2] copy (OK):
Copied 1 items to 'C:/temp/alpha'

[3] list (OK):
=== C:/temp ===
alpha/
go.mod

Requirements

• Go 1.26+
• Bash (Git Bash on Windows, or native Bash on Linux/macOS)
• A running LLM server (LM Studio recommended)

Installation

# Clone the repository
git clone https://github.com/yourusername/termagent_v2.git
cd termagent_v2

# Build
go build -o termagent .

# Add to your PATH
export PATH="$PATH:$(pwd)"

# Add ?? function to your .bashrc
echo '
??() {
    termagent "$@"
}' >> ~/.bashrc

# Reload
source ~/.bashrc

Windows (Git Bash)

# Build
go build -o termagent.exe .

# Add to PATH (edit ~/.bashrc)
export PATH="$PATH:/c/disco d/agentes_discusion/termagent_v2"

# Add ?? function
echo '
??() {
    termagent.exe "$@"
}' >> ~/.bashrc

source ~/.bashrc

Configuration

Set environment variables before running:

# Required
export AGENT_API_KEY="your-api-key"
export AGENT_BASEURL="http://localhost:1234/v1"
export AGENT_PROVIDER="lmstudio"

# Optional
export AGENT_MODEL="your-model-name"

Providers

Provider	Base URL	Notes
lmstudio	http://localhost:1234/v1	Default, local
openai	https://api.openai.com/v1	Cloud
ollama	http://localhost:11434/v1	Local
anthropic	https://api.anthropic.com	Cloud

Usage

From bash (recommended)

$ ?? listame esta carpeta
$ ?? crear carpeta test
$ ?? copiar go.mod a test
$ ?? listar C:\temp

CLI mode

termagent "listame esta carpeta"
termagent "crear carpeta test"

REPL mode

termagent
> listame esta carpeta
> crear carpeta test
> exit

Piped input

echo "listar esta carpeta" | termagent

How It Works

1. You type ?? <message> in bash
2. Bash calls termagent "<message>"
3. LLM generates JSON tool call(s)
4. Agent resolves paths using resolver.sh
5. Agent executes bash scripts
6. Results print directly in your terminal

Path Resolution

• Relative paths: go.mod → searches current directory
• Subdirectories: modulos/file → resolves to full path
• Absolute Windows paths: C:\temp → works as-is
• Spaces in paths: mi carpeta con espacios → handled correctly

Adding Modules

Create a new directory in modulos/ with two files:

1. Your script (mi_tool.sh)

#!/bin/bash

while [[ $# -gt 0 ]]; do
    case $1 in
        --param1=*) PARAM1="${1#*=}" ;;
        *) echo "Unknown parameter: $1" ;;
    esac
    shift
done

echo "Result: $PARAM1"

2. Catalog file (modulo.md)

## mi_tool
**Description:** Description of what it does
**INPUTS:**
- `param1` (string, required) - Parameter description
**OUTPUTS:**
- `result` (string) - Output description
**Examples:**
- "user input" → {"name":"mi_tool","arguments":{"param1":"value"}}
**Instructions:**
- Special instruction for the LLM

Module Structure

modulos/
├── file/
│   ├── modulo.md
│   ├── create.sh
│   ├── copy.sh
│   └── ...
├── system/
│   ├── modulo.md
│   └── sysinfo.sh
├── core/
│   └── resolver.sh    # Path resolution
└── INDEX.md

License

MIT