Clawd Agent
No description available
Ask AI about Clawd Agent
Powered by Claude ยท Grounded in docs
I know everything about Clawd Agent. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AgentX
Customizable, highly-abstracted, production-grade digital employee infrastructure
A strict 1:1 Python port of the AgentX architecture. Plug in any OpenAI-compatible LLM backend.
English ยท ็ฎไฝไธญๆ ยท ๆฅๆฌ่ช
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.
| Dimension | Goal |
|---|---|
| Customizable | Via AGENTX_* env vars, CLAUDE.md rules system, MCP protocol, and custom Agent definitions, every user builds their own intelligent assistant. Brand, behavior, and toolstack are all replaceable. |
| Highly Abstracted | Recursive self-similar Agent architecture: main thread and sub-agents share the same query() loop. The Provider pattern fully decouples the LLM backend โ drop in any OpenAI-compatible API. 7 permission modes for granular control. |
| Production-Grade | Full async asyncio engine, streaming responses, strict Pydantic validation, automatic context compaction, session persistence, multi-Agent collaboration, error recovery chain, Stop Hooks for safe exit โ every component verified against the TypeScript original then rigorously translated. |
| Digital Employee | Not a "chatbot," but an Agent that reads, writes, executes, verifies, and self-corrects. Fork background sub-Agents, independent Verification Agents, Teammates multi-Agent collaboration โ completing work like a real engineer. |
"Don't just chat with AI. Hire it."
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, andpydantic. - 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
| Dimension | TypeScript Original | Python Port |
|---|---|---|
| Runtime | Bun | Python 3.11+ / asyncio |
| AI SDK | @anthropic-ai/sdk | openai (provider pattern) |
| UI | React + Ink | rich + prompt_toolkit |
| Schema | Zod | pydantic |
| HTTP | fetch (Bun) | httpx (async) |
| Types | TypeScript interfaces | dataclass(frozen=True) + typing |
| MCP | @modelcontextprotocol/sdk | mcp Python SDK |
| CLI | Commander.js | click |
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:
| Tool | Name | Description |
|---|---|---|
| Bash | Bash | Execute shell commands with sandbox support |
| Read | Read | Read files from the local filesystem |
| Write | Write | Write files to the local filesystem |
| Edit | Edit | Edit files with find-and-replace |
| Glob | Glob | Fast file pattern matching |
| Grep | Grep | Powerful search built on ripgrep |
| Agent | Agent | Launch sub-agents for complex tasks |
| WebFetch | WebFetch | Fetch and extract web content |
| WebSearch | WebSearch | Search the web |
| TodoWrite | TodoWrite | Track session progress with checklists |
| NotebookEdit | NotebookEdit | Edit Jupyter notebook cells |
| Skill | Skill | Execute learned skills |
| EnterPlanMode | EnterPlanMode | Switch to plan mode |
| ToolSearch | ToolSearch | Search for deferred tools |
| MCP Tools | Various | Model Context Protocol integration |
| ... | ... | 30+ tools total |
LLM Provider Support
AgentX uses the OpenAI-compatible provider pattern, making it work with virtually any LLM backend:
| Provider | Config |
|---|---|
| OpenAI | --provider openai --model gpt-4o |
| DeepSeek | --provider deepseek --model deepseek-chat |
| Custom | --provider custom --base-url http://localhost:11434/v1 |
| Ollama | --provider custom --base-url http://localhost:11434/v1 --model llama3 |
| vLLM | --provider custom --base-url http://localhost:8000/v1 |
| LiteLLM | --provider custom --base-url http://localhost:4000/v1 |
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:
| Mode | Behavior |
|---|---|
default | Ask for permission on each action |
acceptEdits | Auto-approve file edits, ask for others |
auto | Auto-approve most actions |
plan | Plan mode โ design before executing |
bypassPermissions | Skip all permission checks |
dontAsk | Never ask, deny if not pre-approved |
bubble | Bubble permission requests to parent agent |
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)
| Category | What's Preserved |
|---|---|
| System Prompts | Every word, every line |
| Tool Names | 'Bash', 'Read', 'Edit', etc. |
| Tool Descriptions | Full getSimplePrompt() / getDescription() text |
| Parameter Schemas | Field names, types, .describe() strings |
| Tool Behavior Flags | isReadOnly, isConcurrencySafe, shouldDefer |
| Permission Modes | Enum values match original TypeScript |
| Context Formats | Git status, CLAUDE.md output format |
Adapted for Python
| Category | Adaptation |
|---|---|
| API Layer | Anthropic SDK โ OpenAI SDK (provider pattern) |
| UI Framework | React + Ink โ Rich + prompt_toolkit |
| Concurrency | JS Promises โ Python asyncio |
| Process Mgmt | Bun.spawn โ asyncio.create_subprocess_exec |
| Type System | TS interfaces โ dataclass(frozen=True) + typing |
| Schema | Zod โ Pydantic |
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:
- Prompts and descriptions must be character-for-character translations from the TypeScript original
- Tool names and schemas must match the original exactly
- Python adaptations should be idiomatic (asyncio, dataclass, pydantic)
- Tests required โ maintain 80%+ coverage
License
MIT ยฉ 2026 NoemaZero
Built for the Python ecosystem โ open-source and provider-agnostic.
