A powerful AI coding assistant built with Agentuity that provides autonomous coding help with real-time tool execution. Features a hybrid cloud-local architecture where the AI runs in the cloud but all tool execution happens securely on your local machine.
- File Operations: Read, write, list directories, create directories
- Code Execution: Safe execution of Python, JavaScript, and TypeScript via Riza.io
- Shell Commands: Git operations, npm/bun commands, build tools (safety-checked)
- Diff Visualization: Beautiful file comparisons with delta integration
- Work Context: Remember goals and progress across sessions
- Multi-Language Support: Python, JavaScript, TypeScript, Go codebases
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β Cloud Agent βββββΊβ Local CLI βββββΊβ Local Tools β
β (Claude LLM) β β (Tool Proxy) β β (File System) β
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
Benefits:
- π AI in the cloud - Access to latest Claude models and Agentuity infrastructure
- π Tools run locally - Your files and commands never leave your machine
- π Works anywhere - Same experience locally and deployed to cloud
- π Real-time streaming - See AI thinking and tool execution live
Here's how the hybrid architecture enables secure tool execution:
sequenceDiagram
participant User
participant CLI as CLI Client<br/>(Local)
participant Agent as Cloud Agent<br/>(Claude LLM)
participant Tools as Tool Proxy<br/>(Local)
participant FS as File System<br/>(Local)
User->>CLI: "Fix bug in main.py"
CLI->>Agent: HTTP Request: Message + Context
Note over Agent: AI analyzes request<br/>and decides tools needed
Agent->>CLI: Tool Call: read_file("main.py")
CLI->>Tools: Execute read_file locally
Tools->>FS: Read file from disk
FS-->>Tools: File content
Tools-->>CLI: Tool result
CLI->>Agent: HTTP Response: Tool result
Note over Agent: AI analyzes code<br/>and determines fix
Agent->>CLI: Tool Call: write_file("main.py", fixed_content)
CLI->>Tools: Execute write_file locally
Tools->>FS: Write modified file
FS-->>Tools: Write confirmation
Tools-->>CLI: Success result
CLI->>Agent: HTTP Response: Success
Note over Agent: AI prepares<br/>final response
Agent-->>CLI: Final response with explanation
CLI-->>User: Display: "β
Fixed bug in main.py"
Key Security Features:
- π No file access by cloud - Files never leave your machine
- π‘οΈ Sandboxed execution - Code runs in isolated environments (Riza.io)
- β Command whitelisting - Only safe shell commands allowed
- CLI Client (
cli.js) - Handles user interaction and streams responses - Continuation Handler (
cli/continuation-handler.ts) - Parses tool calls and manages execution flow - Tool Proxy (
cli/tool-proxy.ts) - Executes tools safely in your local environment - Cloud Agent (
src/agents/CloudCoder/) - Claude-powered AI running on Agentuity infrastructure - Tool Interface (
tools/interface.ts) - Shared schemas for tool calls and results
# Clone and install git clone <your-repo> cd CodingAgent bun install # Run setup wizard (creates global 'coder' command) bun run setup # Start local development server bun run dev
# Global command (after setup) coder --interactive # Interactive mode (recommended) coder "What files are in this project?" coder "Create a FastAPI server with authentication" # Alternative: Development mode bun run cli --interactive # Local vs Cloud modes coder --local "analyze this codebase" coder --cloud "help with debugging" # (when cloud configured)
$ coder --interactive ___ _ _ _ _ / __| ___ __| |(_) _ _ __ _ /_\ __ _ ___ _ _ | |_ | (__ / _ \/ _` || || ' \ / _` | / _ \ / _` |/ -_)| ' \| _| \___|\___/\__,_||_||_||_|\__, | /_/ \_\\__, |\___||_||_|\__| |___/ |___/ π¬ You: What does this project do? π€ Agent: I'll analyze the project structure to understand what it does. π§ Using tool: list_directory [Tool executes locally, returns results] This is a Coding Agent built with Agentuity that provides AI-powered coding assistance. It features a hybrid architecture where...
/help- Show available commands and examples/clear- Clear screen and show header/session- Start new conversation session/context- Show current work context and goals/diff- Show git diff with beautiful formatting/quit- Exit gracefully
- Project Detection - Auto-detects git repos, package.json, pyproject.toml
- Session Persistence - Maintains conversation context across interactions
- Beautiful Output - Colored text, loading spinners, progress indicators
- Command History - Remembers your previous interactions
The agent has access to these tools that run on your local machine:
| Tool | Description | Example Usage |
|---|---|---|
| read_file | Read and examine code files | "Show me the main.py file" |
| write_file | Create or modify files | "Create a FastAPI server" |
| list_directory | Explore project structure | "What files are in src/?" |
| create_directory | Create new directories | "Organize code into modules" |
| execute_code | Run code safely (Python/JS/TS) | "Test this function" |
| run_command | Execute shell commands | "Run the tests", "git status" |
| diff_files | Compare file versions | "Show changes in main.py" |
| git_diff | Beautiful git diffs | "What changed since last commit?" |
| set_work_context | Set current goals | "We're building user auth" |
| get_work_context | Check current work | "What are we working on?" |
# Required API_KEY=your_agentuity_api_key # Optional (for code execution) RIZA_API_KEY=your_riza_api_key # Optional (override agent URL) AGENT_URL=https://your-custom-agent.agentuity.cloud/agent_xxx
The CLI automatically detects your agent URLs using agentuity agent list --format json. This means the system works out-of-the-box for any developer who clones the repo.
Local Development:
- Runs agent on
http://127.0.0.1:3500/agent_xxx - All tools execute on your local machine
Cloud Deployment:
- Agent runs on
https://your-deployment.agentuity.cloud/agent_xxx - Tools still execute locally via CLI
CodingAgent/
βββ src/agents/CloudCoder/ # Main agent (works local + cloud)
βββ cli/ # CLI client and tool proxy
β βββ continuation-handler.ts
β βββ tool-proxy.ts
β βββ config-utils.ts
βββ tools/ # Shared tool definitions
βββ scripts/ # Utility scripts
βββ cli.js # Main CLI entry point
βββ agentuity.yaml # Agent configuration
# Start development server bun run dev # Use CLI locally bun run cli --local --interactive # Test dynamic configuration bun run test-config # Show detected agent URLs bun run show-urls # Format and lint bun run format bun run lint
# Test local agent bun run cli --local "test message" # Test configuration detection bun run test-config # Test specific functionality bun run cli --local "run git status" bun run cli --local "list files and create a simple test"
π¬ You: "What's in package.json and what dependencies do we have?" # Agent reads file and analyzes dependencies π¬ You: "Create a simple Express server in server.js" # Agent writes file and explains the code π¬ You: "Show me the project structure" # Agent lists directories and key files
π¬ You: "Create a Python function to calculate fibonacci numbers" # Agent writes fibonacci.py and tests it with execute_code π¬ You: "Fix the bug in src/main.py line 42" # Agent reads file, identifies issue, makes fix, shows diff π¬ You: "Run the tests and show me any failures" # Agent runs npm test and analyzes output
π¬ You: "What changed since my last commit?" # Agent runs git diff with beautiful formatting π¬ You: "We're working on user authentication - set that as our context" # Agent remembers this goal for the session π¬ You: "What are we currently working on?" # Agent shows current work context and progress
- Sandboxed Code Execution: All code runs in Riza.io isolated environments
- Local Tool Execution: Files and commands never leave your machine
- Command Safety: Shell commands are whitelisted and checked
- No Hardcoded Secrets: All API keys via environment variables
- Session Isolation: Each conversation has its own secure context
bun run cli --local "message"- Agent runs on
localhost:3500 - Great for development and testing
- No internet required (except for AI model calls)
bun run cli --cloud "message" - Agent runs on Agentuity cloud
- Perfect for team collaboration
- Same local tool execution
bun run cli "message" # defaults to local
- Automatically chooses best available mode
- Falls back gracefully if one mode unavailable
This coding agent is designed to be easily shared and used by any developer:
- Clone & Go: Works immediately after
git clone+bun install - Dynamic Configuration: Auto-detects any developer's agent IDs
- Zero Config: No setup required for basic local usage
- Portable: Same experience on any machine
- Deploy agent to Agentuity cloud
- Share cloud URL with team
- Everyone uses same
--cloudmode - All tool execution remains local for each developer
"Failed to communicate with agent"
- Check if
bun run devis running for local mode - Verify
API_KEYenvironment variable is set - Try
bun run test-configto check configuration
"Code execution failed"
- Set
RIZA_API_KEYenvironment variable - Check code syntax and language support
- Verify network access to Riza.io
"Command not allowed"
- Shell commands are safety-checked
- Use allowed commands: git, npm, bun, python, node, etc.
- Check command whitelist in tool configuration
# Test configuration bun run test-config # Check agent URLs bun run show-urls # Test with simple message bun run cli --local "hello"
- Fork & Clone: Standard GitHub workflow
- Local Development: Use
bun run dev+bun run cli --local - Add Tools: Extend
tools/interface.tsfor new capabilities - Test: Verify both local and cloud modes work
- Document: Update this README for new features
export AGENT_URL="https://custom-agent.example.com/agent_xxx" bun run cli "message"
# Use specific session bun run cli --session my-project-auth "continue previous work"
// Direct API usage const response = await fetch('http://127.0.0.1:3500/agent_xxx', { method: 'POST', headers: { 'Content-Type': 'text/plain', 'Authorization': `Bearer ${API_KEY}`, 'x-session-id': 'unique-session' }, body: 'Your coding request here' });