⚛️ Arrgon

Free, open-source AI coding agent server for Google Gemini

Turn the free Gemini Desktop App into a powerful autonomous coding agent — reads files, writes code, runs tests, and verifies its own changes — all locally on your machine.

Quickstart • How It Works • Security • Tools • Customization • Contributing

💡 What is Arrgon?

Arrgon is a local Model Context Protocol (MCP) server that gives Google Gemini the ability to read, write, search, and patch code files — and run developer commands like flutter analyze, pytest, git diff, npm test, etc. — all inside a sandboxed, zero-shell environment on your machine.

Use Gemini as a free AI coding agent. No API keys. No subscriptions. Just connect Arrgon to the Gemini Desktop App and start prompting.

What can you do with it?

• 🔍 "Read lib/main.dart and find all TODO comments in the project"
• ✏️ "Add error handling to the fetchUser() function and run flutter analyze to check for issues"
• 🧪 "Write a unit test for the auth module, then run pytest to verify it passes"
• 🔄 "Refactor utils.py to use dataclasses and check git diff to review the changes"

Gemini autonomously loops through read → edit → verify cycles until the task is done.

🚀 Quickstart (2 Minutes)

Prerequisites

• Python 3.10+ installed (python.org)
• Gemini Desktop App installed (gemini.google.com/app)

Step 1: Clone & Install

git clone https://github.com/omkar-ukirde/Arrgon.git
cd Arrgon

python3 -m venv .venv
source .venv/bin/activate      # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Step 2: Connect to Gemini Desktop App

Open the Gemini Desktop App → Settings (gear icon) → Connected Apps → Add custom connected app.

You will see two setup methods. Use Local MCP (recommended):

Option A: Local MCP (Recommended)

The Gemini app launches and manages the server process for you. Zero maintenance.

Command — paste the full path to start_mcp.sh:

/full/path/to/Arrgon/start_mcp.sh

Example (on macOS):

/Users/yourname/Arrgon/start_mcp.sh

💡 Changing your project folder:

• Edit DEFAULT_WORKSPACE inside start_mcp.sh to point to whatever project directory you want to work on (e.g., /Users/yourname/MyProject), or
• Pass the directory directly as an argument in the Command field: /Users/yourname/Arrgon/start_mcp.sh /Users/yourname/MyProject
• Always choose Full access under Sandbox settings so Arrgon can read and write to your workspace without permission errors.

Click Next → Connect, and you're done!

Option B: Cloud MCP (HTTP Mode)

If you prefer running the server yourself in a terminal (useful for debugging or switching projects):

1. Start the server:

cd Arrgon
./run_server.sh /path/to/your/project

2. In Gemini Desktop App, choose Cloud MCP and enter:

Note: You must keep the terminal running. Closing it stops the server.

Step 3: Start Coding with Gemini

Go back to the Gemini chat and try:

"List all files in my project and give me an overview of the codebase structure"

Gemini will call Arrgon's tools to browse your files, read code, and respond with a structured overview. From there, you can ask it to make changes, run tests, debug errors — anything a coding assistant would do.

⚙️ How It Works

┌─────────────────────┐        MCP (stdio or HTTP)        ┌──────────────────────┐
│   Gemini Desktop    │ ◄──────────────────────────────► │       Arrgon         │
│   App (free)        │    JSON-RPC tool calls            │   MCP Server         │
│                     │                                    │                      │
│  "Fix the bug in    │  ──► read_file("src/app.py")      │  Reads files         │
│   src/app.py and    │  ◄── file content with line #s    │  Writes atomically   │
│   run the tests"    │  ──► patch_file(search, replace)  │  Searches code       │
│                     │  ◄── "Successfully patched"       │  Runs safe commands  │
│                     │  ──► run_command("pytest")        │                      │
│                     │  ◄── test results                 │  All sandboxed to    │
│                     │                                    │  your workspace dir  │
└─────────────────────┘                                    └──────────────────────┘

Arrgon exposes 8 MCP tools that Gemini calls autonomously. Gemini decides which tools to call and in what order — forming edit → verify loops on its own.

🛡️ Security

Arrgon is designed to be safe for autonomous AI usage on your local machine. Every operation is sandboxed.

run_command — Zero-Shell Terminal Runner

The run_command tool is the most security-critical component. Here's what makes it safe:

Filesystem Sandbox

🔧 Available Tools

🎛️ Customization

Environment Variables

Adding More Commands

Edit the ALLOWED_COMMANDS dictionary in mcp_coding_agent.py to allow more tools:

ALLOWED_COMMANDS: dict[str, Optional[set[str]]] = {
    # Add your own:
    "cargo": {"build", "test", "check", "clippy"},
    "go":    {"build", "test", "vet", "fmt"},
    "make":  {"test", "build", "lint"},
    # ... existing entries ...
}

Set a value of None to allow any subcommand for a binary (only for trusted tools like test runners):

"mypy": None,  # Any arguments are allowed

Switching Projects

Local MCP: Edit the command in Gemini Desktop App settings to point to a different workspace directory.

Cloud MCP: Stop the server (Ctrl+C) and restart with a new path:

./run_server.sh /path/to/different/project

🧪 Running Tests

Arrgon includes 18 automated tests covering command validation, path security, file operations, and HTTP endpoint integration:

source .venv/bin/activate
pytest -v

test_mcp_coding_agent.py::test_validate_command_allowed PASSED
test_mcp_coding_agent.py::test_validate_command_shell_operators_blocked PASSED
test_mcp_coding_agent.py::test_validate_command_blocked_tokens PASSED
test_mcp_coding_agent.py::test_validate_command_unauthorized_binaries_and_subcommands PASSED
test_mcp_coding_agent.py::test_validate_command_empty PASSED
test_mcp_coding_agent.py::test_resolve_safe_path_valid PASSED
test_mcp_coding_agent.py::test_resolve_safe_path_traversal_blocked PASSED
test_mcp_coding_agent.py::test_write_and_read_file PASSED
test_mcp_coding_agent.py::test_read_file_errors PASSED
test_mcp_coding_agent.py::test_patch_file PASSED
test_mcp_coding_agent.py::test_search_code PASSED
test_mcp_coding_agent.py::test_list_files PASSED
test_mcp_coding_agent.py::test_move_or_rename_file PASSED
test_mcp_coding_agent.py::test_delete_file PASSED
test_mcp_coding_agent.py::test_run_command_allowed_execution PASSED
test_mcp_coding_agent.py::test_run_command_blocked PASSED
test_mcp_coding_agent.py::test_run_command_invalid_directory PASSED
test_mcp_coding_agent.py::test_streamable_http_initialization_and_tool_list PASSED

============================== 18 passed ==============================

📁 Project Structure

Arrgon/
├── mcp_coding_agent.py        # Main MCP server (all tools + security)
├── test_mcp_coding_agent.py   # Automated test suite (18 tests)
├── run_server.sh              # Helper script for HTTP mode
├── requirements.txt           # Python dependencies
├── LICENSE                    # MIT License
└── README.md                  # This file

🤝 Contributing

Contributions are welcome! Some ideas:

• Add more tool commands (Rust/Cargo, Go, Make, Docker, etc.)
• Add a create_directory tool for scaffolding projects
• Add undo_patch with file backup/restore
• Windows support improvements (PATH handling, shell detection)
• Multi-workspace support for monorepos

# Fork, clone, and run tests
git clone https://github.com/YOUR_USERNAME/Arrgon.git
cd Arrgon
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pytest -v

📄 License

MIT License — use it however you want, free forever.

_{Built with ❤️ for the developer community. Give Gemini superpowers. Star ⭐ if you find this useful!}