🤖 Coding Agent

Build Agents, Not Infrastructure

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.

✨ Features

🔧 Core Capabilities

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

🏗️ Hybrid Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   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

🔄 Tool Execution Flow

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

Technical Components

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

🚀 Quick Start

1. Setup

# 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

2. Use the CLI

# 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)

3. Example Session

$ 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...

🎨 CLI Features

🔧 Interactive Commands

/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

🎯 Smart Features

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

🛠️ Available Tools

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?"

⚙️ Configuration

Environment Variables

# 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

Agent URLs (Auto-detected)

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

🔧 Development

Project Structure

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

Development Commands

# 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

Testing

# 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"

🚦 Usage Examples

File Operations

💬 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

Code Development

💬 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

Git & Project Management

💬 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

🔒 Security

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

🎯 CLI Modes

Local Mode (Default)

bun run cli --local "message"

Agent runs on localhost:3500
Great for development and testing
No internet required (except for AI model calls)

Cloud Mode

bun run cli --cloud "message"

Agent runs on Agentuity cloud
Perfect for team collaboration
Same local tool execution

Auto Mode

bun run cli "message"  # defaults to local

Automatically chooses best available mode
Falls back gracefully if one mode unavailable

🚀 Distribution

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

For Teams

Deploy agent to Agentuity cloud
Share cloud URL with team
Everyone uses same --cloud mode
All tool execution remains local for each developer

🐛 Troubleshooting

Common Issues

"Failed to communicate with agent"

Check if bun run dev is running for local mode
Verify API_KEY environment variable is set
Try bun run test-config to check configuration

"Code execution failed"

Set RIZA_API_KEY environment 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

Debug Commands

# Test configuration
bun run test-config

# Check agent URLs
bun run show-urls

# Test with simple message
bun run cli --local "hello"

🤝 Contributing

Fork & Clone: Standard GitHub workflow
Local Development: Use bun run dev + bun run cli --local
Add Tools: Extend tools/interface.ts for new capabilities
Test: Verify both local and cloud modes work
Document: Update this README for new features

📚 Advanced Usage

Custom Agent URLs

export AGENT_URL="https://custom-agent.example.com/agent_xxx"
bun run cli "message"

Session Management

# Use specific session
bun run cli --session my-project-auth "continue previous work"

Integration Examples

// 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'
});

Built with ❤️ using Agentuity and Riza.io

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.cursor/rules		.cursor/rules
cli		cli
docs		docs
scripts		scripts
src		src
tools		tools
.editorconfig		.editorconfig
.gitignore		.gitignore
AGENT.md		AGENT.md
CLAUDE.md		CLAUDE.md
README.md		README.md
agentuity.yaml		agentuity.yaml
biome.json		biome.json
bun.lock		bun.lock
cli.js		cli.js
index.ts		index.ts
package.json		package.json
test-client.js		test-client.js
test-cloud.js		test-cloud.js
test-riza-error.js		test-riza-error.js
tsconfig.json		tsconfig.json

agentuity/agent-coder

Folders and files

Latest commit

History

Repository files navigation