GhoulAI

An intelligent AI-Agent command-line assistant with autonomous reasoning capabilities.

About The Project

GhoulAI is a command-line AI agent that combines OpenAI's language models with a structured reasoning framework to accomplish tasks through natural language. From checking the weather to running full development workflows, it analyzes intent, plans a sequence of actions, executes them through a tool suite, and self-corrects when something fails — rather than just forwarding a prompt straight to a single tool call.

Key Features

• Multi-phase autonomous reasoning loop: Start → Plan → Action → Observe → Result
• Deep intent analysis and strategic task breakdown before acting
• Self-correcting execution with built-in error handling
• Real-time weather lookups for any city
• Terminal command execution and shell operations
• File reading, searching, and codebase analysis
• Code search across project files for patterns and text
• Git integration for staging, committing, and version control tasks
• Docker container orchestration support
• File writing and editing — creating, modifying, and refactoring files directly

Technology Stack

• Python 3.13+
• OpenAI API
• Rich (terminal UI)
• Requests

Architecture

GhoulAI is organized around a small set of focused modules: an agent.py handling branding and intro, a setup.py running the main conversation loop and AI interaction, a tools.py holding all available tool implementations, a prompt.py defining the system prompt and overall agent behavior, and a helpers.py for UI display utilities. The reasoning loop itself walks through distinct phases — understanding what the user wants, forming a plan, executing a tool call, observing the result, and reporting back — rather than treating each user message as a single isolated request.

Safety & Security

• Command execution has a hard 30-second timeout to prevent runaway processes
• API keys are managed entirely through environment variables, never hardcoded
• Agent-to-tool communication follows a structured JSON protocol
• Web search is deliberately disabled as a security boundary

Example Workflows

GhoulAI handles requests ranging from simple lookups to multi-step development tasks — checking weather for a city, searching a codebase for TODO comments, scaffolding a full React app with Vite, or staging and committing multiple files with individually generated commit messages — all through the same plan-act-observe loop.

Problems Faced

1. Structuring Autonomous Reasoning : Getting an LLM to reliably plan before acting, rather than jumping straight to a tool call, required building an explicit phase structure (Start → Plan → Action → Observe → Result) into the prompt and loop logic rather than relying on the model to self-organize.

2. Balancing Capability Against Safety : Giving the agent real terminal, file-system, and git access meant every capability had to be paired with a safety constraint — command timeouts, restricted scopes, and deliberately disabling web search to keep the blast radius of any single action bounded.

3. Designing a Reliable Tool Protocol : Coordinating between the LLM's natural-language reasoning and actual function execution required a structured JSON communication protocol so tool calls and their results could be parsed and acted on deterministically.

Key Learnings

1. Explicit Phases Beat Implicit Reasoning : Forcing the agent through distinct plan/act/observe phases produced far more reliable behavior than expecting a single model call to reason, act, and self-correct all at once.

2. Tool Design Is an Extension Point, Not an Afterthought : Structuring tools.py so new tools can be added with a simple function plus a registration entry made the agent meaningfully extensible without touching the core reasoning loop.

3. Guardrails Matter More As Capability Grows : The more real-world actions an agent can take (running commands, editing files, committing code), the more its safety constraints — timeouts, scoped permissions, disabled risky tools — become as important as its actual intelligence.