A S H B O R N   A G E N T

The Ultimate Autonomous Architect — Think. Plan. Execute. Reflect.

   

---

🔥 What is Ashborn?

Ashborn is a fully autonomous AI development agent that transforms natural-language intent into production-ready code. It doesn't just generate — it thinks, plans, executes, and reflects through a sophisticated multi-phase cognition loop, delivering surgical precision even on complex, multi-file projects.

Built on the high-performance Phoenix AI Framework, Ashborn ships as both a standalone IDE (powered by VSCodium) and a cinematic terminal interface — giving you the freedom to work wherever you're most productive.

🧠 Not Just Another Copilot Unlike code completion tools that react to keystrokes, Ashborn operates at a project level. Give it a goal, and it will: Decompose it into discrete tasks Generate execution plans with dependency ordering Write, edit, and test files autonomously Self-evaluate results and iterate

⚡ Built for Real Work Ashborn is designed for professional-grade output: Surgical file editing — no "rewrite the whole file" User approval gates for destructive actions Streaming feedback so you see every thought Resume-capable state persistence

---

✨ Features

Multi-Phase Cognition Think → Plan → Generate → Act → Reflect	Surgical Code Editing Line-range & search/replace precision	Dual Interface Standalone IDE + Cinematic TUI	Safety-First Execution Approval gates & forbidden patterns
Real-Time Streaming SSE-powered live thought feed	Persistent State Backbone context file for resume	Voice I/O Speech-to-text & text-to-speech	Extensible Tools Drop-in tool registration system

---

⚡ Quickstart

Prerequisites

Requirement	Version
🐍 Python	>= 3.10
📦 pip	Latest
🐧 OS	Linux (Ubuntu/Debian/Arch)

1 · Clone & Setup

git clone https://github.com/your-org/ashborn-agent.git
cd ashborn-agent

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -e .
pip install -r requirements.txt

2 · Configure

Create a .env file in the project root:

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_LLM_MODEL=gpt-4o

3 · Launch

🖥️ Terminal Mode (TUI) ashborn .

🏢 IDE Mode (Standalone) python launch.py .

4 · Server Only (API Mode)

uvicorn ashborn.server:app --host 127.0.0.1 --port 8765

---

🌐 API Reference

Ashborn exposes a RESTful API for programmatic integration.

💬 Chat & Agent

Method	Endpoint	Description
POST	/chat/stream	Stream agent response (SSE)
POST	/tool/result	Return VS Code tool call result
POST	/reset	Reset the current session

Stream a request:

curl -N -X POST http://localhost:8765/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"task": "Create a Flask REST API", "mode": "plan"}'

💡 Code Intelligence

Method	Endpoint	Description
POST	/completion	Inline code completion
POST	/code_action	Explain / Refactor / Optimize / Fix

⚙️ Configuration

Method	Endpoint	Description
GET	/config	Get current configuration
POST	/config	Update .env and re-init agent

🎤 Media (Voice)

Method	Endpoint	Description
POST	/tts	Text-to-speech (gTTS → base64 MP3)
POST	/stt/start	Start microphone recording
POST	/stt/stop	Stop recording & transcribe

❤️ Health

Method	Endpoint	Description
GET	/health	Server & agent readiness check

curl http://localhost:8765/health
# → {"status": "ok", "agent_ready": true}

---

🔧 Agent Tools

Ashborn ships with a curated set of tools the agent uses autonomously:

Tool	Description
📖 file_read_lines	Read file with line numbers for precise targeting
✏️ file_update_multi	Surgical multi-block edits (line-range + search/replace)
📝 file_write	Create new files with automatic directory creation
🔍 vscode_search	Workspace-wide regex search via VS Code
📂 vscode_create_file	Create files through the IDE bridge
🔄 vscode_edit_file	Edit files with diff preview & user approval
🗑️ vscode_delete_file	Delete files with confirmation prompt
💻 vscode_terminal_run	Execute terminal commands via VS Code
🏗️ project_generator	Scaffold entire project structures from a dict manifest
⚙️ terminal	Sandboxed bash execution with security guards

---

📸 Screenshots

Ultra-Premium IDE Interface	Cinematic Terminal Experience
Phoenix AI Cognition Core	Autonomous Workflow Cycle

---

📦 Distribution

Build a Distributable Package

bash scripts/package.sh

Outputs a production-ready archive at dist/ashborn-ide-linux.tar.gz containing the extension, backend, and one-step installer.

Install from Bundle

tar -xzf ashborn-ide-linux.tar.gz
bash install.sh

The installer handles VSCodium download, Python venv creation, and desktop integration automatically.

---

Phoenix AI Framework 🔥 A production-ready, modular backend infrastructure SDK designed for AI-powered Python services. View Phoenix AI Framework 🧩 Module Description phoenix.agent Agent lifecycle, autonomous loop orchestration & tool dispatch phoenix.cognition Thinker, Planner & Reflector — modular reasoning base classes phoenix.llm High-performance streaming LLM interface (OpenAI-compatible) phoenix.memory Semantic memory, vector storage & context management phoenix.tools Extensible tool system with built-in FileRead, FileEdit & more

---

📖 Documentation

Resource	Description
🚀 Quickstart	Get up and running in 2 minutes
🌐 API Reference	All REST endpoints documented
🔧 Tools	Agent tool capabilities
📦 Distribution	Build & ship packages

---

🤝 Contributing

Contributions are welcome! The modular architecture makes it easy to add new capabilities:

• New Brain Module → Add to ashborn/cognition/brains/
• New Tool → Create in ashborn/tools/ and register in agent.py
• New API Route → Add a routes_*.py in ashborn/backend/
• New Prompt → Add to ashborn/cognition/core/prompts.py

---

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

A S H B O R N
<sub>The Ultimate Autonomous Architect

Built with 🔥 by Mohammed Alaa
Powered by Phoenix AI Framework</sub>