🤖 My TUI Coding Agent

A lightweight, powerful terminal-based (TUI) autonomous coding AI agent built in Python. It features an event-driven ReAct loop that executes file reading, file writing, directory creation, shell commands, codebase search, and loops observations back to the AI model until the task is complete.

---

📐 Agent Control Flow & Pseudocode

                               ┌────────────────────────┐
                               │  User Input (Prompt)   │
                               └───────────┬────────────┘
                                           │
                                           ▼
                               ┌────────────────────────┐
                               │   Add to Context       │
                               └───────────┬────────────┘
                                           │
                        ┌──────────────────┴──────────────────┐
                        │                                     │
                        ▼                                     │
             ┌─────────────────────┐                          │
             │   Call LLM API      │                          │
             │ (Strict JSON Model) │                          │
             └──────────┬──────────┘                          │
                        │                                     │
                        ▼                                     │
             ┌─────────────────────┐                          │
             │ Does response contain│                          │
             │    "calls"?         │                          │
             └──────────┬──────────┘                          │
                        │                                     │
            YES         │         NO                          │
      ┌─────────────────┴─────────────────┐                   │
      ▼                                   ▼                   │
┌───────────────────────────┐   ┌───────────────────┐         │
│  Tool Calling Section     │   │  Print AI Response│         │
│  -----------------------  │   │  Break Loop /     │         │
│  1. Parse tool name & args│   │  Wait for User    │         │
│  2. Display in TUI        │   └───────────────────┘         │
│  3. Run Executor          │                                 │
│  4. Display Observation   │                                 │
│  5. Append Observation    │                                 │
│     to Context History    │                                 │
└─────────────┬─────────────┘                                 │
              │                                               │
              └───────────────────────────────────────────────┘
                        Loop Back to AI Turn

Pseudocode Implementation

while turn < max_turns:
    # 1. Ask LLM for next action in strict JSON
    ai_output = llm.generate(messages)

    # 2. Check if AI requested tool execution
    if ai_output.has_tool_calls():
        for tool_call in ai_output.calls:
            # Display step in TUI
            tui.display_tool_call(tool_call)

            # Execute tool action (read, write, command, list, grep)
            result = dispatch_tool(tool_call.name, tool_call.args)

            # Display observation
            tui.display_tool_result(result)

            # Append observation to context
            messages.append({"role": "observation", "content": result})

        # LOOP BACK TO AI
        continue
    else:
        # NO TOOL CALLS -> Print final response & break loop
        tui.display_agent_response(ai_output.response)
        break

---

🛠️ Included Tool Executors

Tool Name	Parameters	Description
read_file	path, start_line, end_line	Reads file contents with line numbers
write_file	path, content, create_dirs	Writes/creates file and parent directories
create_directory	path	Creates directory structure
list_dir	path, recursive	Lists files and subdirectories with sizes
run_command	command, cwd, timeout	Executes shell commands (Bash/PowerShell)
grep_search	query, path, case_sensitive	Searches codebase for regular expressions/text

---

🚀 Quick Start

1. Installation

Install requirements (rich and requests):

pip install -r requirements.txt

2. Set API Key (Optional)

You can set your Gemini or OpenAI API key:

Windows (PowerShell):

$env:GEMINI_API_KEY="your-gemini-api-key"

Linux / macOS:

export GEMINI_API_KEY="your-gemini-api-key"

Note: If no API key is provided, the agent automatically runs in Dry-Run / Mock Simulator Mode so you can test the full TUI workflow locally!

3. Run Interactive TUI

python main.py

4. Run Single Prompt Command

python main.py --prompt "List files and create a sample index.html page"

5. Run Test Suite

python test_demo.py

---

📂 Project Structure

• main.py: CLI & Interactive TUI application entry point.
• agent.py: Core ReAct Agent turn loop logic.
• llm.py: Multi-provider LLM API client (Gemini, OpenAI, Ollama, Dry-Run).
• executors.py: Tool dispatchers (File I/O, Shell execution, Directory creation, Grep search).
• tui.py: Rich terminal user interface component renderer.
• test_demo.py: Demo simulation script.