Clawd Agent

Vision

Build a customizable, highly-abstracted, production-grade digital employee.

AgentX is more than an AI coding CLI — it aims to be the digital employee infrastructure that every individual and team can customize on demand.

Why This Project?

The agentic coding CLI paradigm has proven transformative for developer productivity, but existing implementations are tightly coupled to specific SDKs and runtimes. AgentX breaks this coupling.

AgentX is a strict, architecture-level port of the agentic coding CLI concept into idiomatic Python. Every prompt, tool name, parameter schema, and behavioral flag is carefully preserved, while the runtime is rebuilt on Python's async ecosystem and the OpenAI-compatible provider pattern — so you can plug in any LLM backend (OpenAI, DeepSeek, Ollama, vLLM, LiteLLM, etc.).

Key Goals

• Strict fidelity — System prompts, tool descriptions, schemas, and permission modes are character-for-character translations of the original.
• Provider agnostic — Uses the OpenAI SDK as a universal interface. Swap backends via --provider / env vars.
• Pure Python, async-native — Built on asyncio, rich, prompt_toolkit, and pydantic.
• Full tool parity — All 30+ built-in tools faithfully translated, plus MCP protocol support.

Architecture

The architecture is a direct mirror of the original TypeScript source. See docs/IMPLEMENTATION_STEPS.md for the full translation guide.

┌─────────────────────────────────────────────────────────┐
│                      CLI / REPL                         │
│              main.py  ·  ui/repl.py                     │
├───────────────────────┬─────────────────────────────────┤
│    QueryEngine        │         State Management        │
│  engine/query_engine  │        state/app_state          │
│  engine/query.py      │        state/store              │
├───────────────────────┼─────────────────────────────────┤
│    LLM Service        │       Tool System (30+)         │
│  services/api/client  │  tools/bash_tool                │
│  services/llm/        │  tools/file_read_tool           │
│  services/compact/    │  tools/file_edit_tool           │
│                       │  tools/agent_tool  ...          │
├───────────────────────┼─────────────────────────────────┤
│  Permission System    │     Advanced Features           │
│  permissions/checker  │  commands/   (slash commands)   │
│  permissions/classify │  memory/     (CLAUDE.md + mem)  │
│  permissions/modes    │  tasks/      (multi-agent)      │
│                       │  services/mcp/ (MCP protocol)   │
└───────────────────────┴─────────────────────────────────┘

Tech Stack Mapping

Quick Start

Prerequisites

• Python 3.11+
• An API key for any OpenAI-compatible provider

Installation

# Install via pip (recommended)
pip install agent-x

Or install from source:

# Clone the repo
git clone https://github.com/NoemaZero/AgentX.git
cd AgentX

# Create virtual environment
python -m venv env
source env/bin/activate  # or `env\Scripts\activate` on Windows

# Install as editable package
pip install -e .

Configuration

Set your API credentials via environment variables:

# OpenAI
export OPENAI_API_KEY="sk-..."

# Or DeepSeek
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.deepseek.com"

# Or any OpenAI-compatible endpoint (Ollama, vLLM, LiteLLM...)
export OPENAI_API_KEY="your-key"
export OPENAI_BASE_URL="http://localhost:11434/v1"

Usage

# Interactive REPL
python -m AgentX

# Single query (non-interactive)
python -m AgentX "fix the bug in main.py"

# Specify model / provider
python -m AgentX --model gpt-4o
python -m AgentX --provider deepseek --model deepseek-chat

# Permission modes
python -m AgentX --permission-mode auto
python -m AgentX --permission-mode plan

# Verbose output
python -m AgentX -v

Or use the installed CLI:

agent-x "explain this codebase"
agent-x --model gpt-4o --max-turns 10

Tool System

All 30+ tools are strict translations of the original AgentX tool definitions, preserving exact names, descriptions, and parameter schemas:

LLM Provider Support

AgentX uses the OpenAI-compatible provider pattern, making it work with virtually any LLM backend:

Demo: Gomoku (Five-in-a-Row)

The example/gomoku/ directory showcases a complete Gomoku game generated entirely by AgentX — from the game board rendering to the AI opponent logic.

Features of the generated game:

• 🎮 PvP & PvE modes — Play against another human or an AI opponent
• 🤖 4 AI difficulty levels — Easy, Medium, Hard, Expert
• ✨ Particle background effects — Animated CSS particles
• ↩️ Undo support — Take back moves
• 📱 Responsive design — Works on desktop and mobile

Try it yourself:

# Open the game in your browser
open example/gomoku/index.html

This demo illustrates the full agentic workflow: AgentX reads the requirements, plans the architecture, writes HTML/CSS/JS files, and iterates until the game is complete — all through the tool system.

Permission System

Strict translation of the original permission modes:

Extensibility & SDK

AgentX is designed as a developer framework. Use it programmatically or build custom tools.

Programmatic API

import asyncio
from AgentX.config import load_config
from AgentX.engine.query_engine import QueryEngine
from AgentX.ui.stream_renderer import StreamRenderer
from rich.console import Console

async def main():
    config = load_config(
        model="gpt-4o",
        api_key="sk-...",
        provider="openai",
    )
    engine = QueryEngine(config)
    await engine.initialize()

    renderer = StreamRenderer(Console())
    async for event in engine.submit_message("Explain this codebase"):
        await renderer.render_event(event)

asyncio.run(main())

Create a Custom Tool

from AgentX.tools.base import BaseTool, ToolResult

class WeatherTool(BaseTool):
    name: str = "get_weather"
    description: str = "Get current weather for a city"
    is_read_only: bool = True

    def get_parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name"
                }
            },
            "required": ["city"],
        }

    async def execute(self, *, tool_input: dict, cwd: str, **kwargs) -> ToolResult:
        city = tool_input.get("city", "Unknown")
        # Call your API here
        return ToolResult(data=f"Weather in {city}: 25°C, sunny")

# Register with the engine
engine = QueryEngine(config)
engine.register_tool(WeatherTool())

Project Structure

AgentX/
├── main.py                 # CLI entry point (→ main.tsx)
├── config.py               # Configuration (→ entrypoints/init.ts)
├── data_types.py           # Core types (→ Tool.ts + types/)
│
├── constants/              # Prompts & constants (strict translation)
│   ├── prompts.py          # System prompts (→ constants/prompts.ts)
│   └── cyber_risk.py       # Security instruction (→ cyberRiskInstruction.ts)
│
├── engine/                 # Core engine
│   ├── query_engine.py     # QueryEngine (→ QueryEngine.ts)
│   ├── query.py            # Query loop (→ query.ts)
│   └── context.py          # Context builder (→ context.ts)
│
├── services/               # Service layer
│   ├── api/                # LLM API client (→ services/api/)
│   ├── llm/                # Provider pattern (OpenAI/DeepSeek/Custom)
│   ├── compact/            # Context compaction (→ services/compact/)
│   ├── mcp/                # MCP protocol (→ services/mcp/)
│   └── tools/              # Tool orchestration (→ services/tools/)
│
├── tools/                  # 30+ built-in tools (→ tools/)
│   ├── base.py             # Tool base class (→ Tool.ts)
│   ├── bash_tool.py        # Shell execution (→ BashTool/)
│   ├── file_read_tool.py   # File reading (→ FileReadTool/)
│   ├── file_edit_tool.py   # File editing (→ FileEditTool/)
│   ├── agent_tool.py       # Sub-agents (→ AgentTool/)
│   └── ...                 # All other tools
│
├── permissions/            # Permission system (→ utils/permissions/)
├── commands/               # Slash commands (→ commands.ts)
├── tasks/                  # Multi-agent tasks (→ tasks/)
├── memory/                 # Memory system (→ memdir/)
├── state/                  # State management (→ state/)
├── ui/                     # Terminal UI (→ screens/ + ink/)
└── utils/                  # Utilities (→ utils/)

Translation Principles

Strictly Preserved (Character-for-Character)

Adapted for Python

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check AgentX/

# Type check
mypy AgentX/

Documentation

• IMPLEMENTATION_STEPS.md — Full 8-phase implementation guide with strict translation rules
• SOURCE_EXTRACTION.md — Exact strings extracted from the original TypeScript source for translation reference

Contributing

Contributions are welcome! When contributing, please follow the translation principles:

1. Prompts and descriptions must be character-for-character translations from the TypeScript original
2. Tool names and schemas must match the original exactly
3. Python adaptations should be idiomatic (asyncio, dataclass, pydantic)
4. Tests required — maintain 80%+ coverage

License

MIT © 2026 NoemaZero