Arche Code

Model-agnostic CLI agent that turns any LLM into an autonomous coding assistant.

---

What It Does

Arche Code is a terminal-native AI agent for code generation, editing, refactoring, debugging, and testing. It is built around a pluggable model provider system — swap the backend without changing your workflow.

Supported providers:

• Arche — our own fine-tuned models via HuggingFace transformers
• OpenAI — GPT-4, GPT-3.5 via API
• Local — GGUF via llama.cpp, Ollama endpoints, or any local checkpoint
• Stub — zero-dependency fallback for testing and CI

---

Installation

Option 1: Editable install (recommended for development)

git clone https://github.com/OpenSynapseLabs/arche-code.git
cd arche-code
pip install -e .

This creates an editable installation. Changes to the source code are reflected immediately without re-installing.

Option 2: Manual install (lightweight, no package metadata)

git clone https://github.com/OpenSynapseLabs/arche-code.git
cd arche-code
pip install -r requirements.txt

Then run via module:

python -m arche_code

---

Quick Start

# Write code from a description
arche write "a FastAPI endpoint that validates JWT tokens"

# Edit a file in-place (with confirmation)
arche edit app.py "add rate limiting middleware"

# Refactor for performance
arche refactor app.py --goal "reduce database round trips"

# Analyze quality
arche analyze app.py

# Generate tests
arche test app.py

# Debug from an error traceback
arche debug app.py "AttributeError: 'NoneType' object has no attribute 'split'"

# Interactive chat mode
arche chat

# Interactive REPL shell
arche shell

---

Architecture

Provider System (model.py)

from arche_code import ModelConfig, ArcheAgent

# Arche model (local)
config = ModelConfig(provider="arche", local_path="~/.arche/models/arche-codium-500m")
agent = ArcheAgent(config)

# OpenAI
config = ModelConfig(provider="openai", api_key="sk-...", model_name="gpt-4")
agent = ArcheAgent(config)

# Local GGUF
config = ModelConfig(provider="local", local_path="./models/deepseek-coder-6.7b-q4.gguf")
agent = ArcheAgent(config)

Providers are auto-registered via ModelRegistry. Adding a new backend means subclassing ModelProvider and implementing four methods: load(), generate(), is_ready(), get_info().

Agent Core (agent.py)

The ArcheAgent class exposes six task types:

Method	Task	Output
write()	Generate from description	Code block
edit()	Apply instruction to existing code	Patched code
refactor()	Restructure against a goal	Refactored code
analyze()	Static quality review	Markdown report
generate_test()	Unit tests from source	Test file
debug()	Fix from error message	Corrected code

Each call returns a TaskResult with success flag, output text, error string, iteration count, and metadata dict. Task history is tracked and queryable via agent.get_history().

File Access (cli.py)

The FileAccessManager enforces opt-in consent before reading any path:

• Per-file prompts on first access
• Optional global consent flag
• /read <path> and /ls <path> commands inside chat mode

Code Tools

Module	Function
editor.py	AST-aware function/class replacement with undo stack
parser.py	Regex + AST extraction of functions, classes, imports
validators.py	Syntax check, naming conventions, line length, docstring coverage
tester.py	Execution via sys.executable, pytest runner, coverage, import validation
project.py	Scaffold new projects with src/, tests/, docs/ layout

Plugin System (hooks.py)

from arche_code import Plugin, HookType

class MyPlugin(Plugin):
    def get_hooks(self):
        return [
            (HookType.PRE_WRITE, self.lint_before_write),
            (HookType.POST_EDIT, self.format_after_edit),
        ]

Hooks execute in priority order. The bundled PreCommitHook validates syntax before any write or edit operation.

---

Interactive Modes

Chat Mode

$ arche chat
💬 Chat Mode
Type 'exit' or 'quit' to leave, 'clear' to clear history

You: how do I memoize a recursive Fibonacci in Python?
Arche: [generated explanation + code block]

You: /read ./src/utils.py
[file content rendered with syntax highlighting]

Maintains rolling conversation history (last 10 turns). Supports file read and directory listing commands.

Shell Mode

$ arche shell
╔════════════════════════════════════════════════════════════╗
║ Arche Code Shell                                           ║
║ Type 'help' for commands                                   ║
╚════════════════════════════════════════════════════════════╝

arche> write "async context manager for SQLite"
arche> parse app.py
arche> validate app.py
arche> status
arche> exit

Tab-completion for all commands. History persisted to ~/.arche_history.

---

Model Download

For Arche models, the CLI can download automatically from HuggingFace:

arche --provider arche --model arche-codium-500m write "hello world in Rust"
# → prompts to download if not found locally

Local cache path: ~/.arche/models/<model_name>

---

Configuration

JSON config at ~/.arche_code/config.json:

{
  "model": {
    "provider": "arche",
    "model_name": "arche-codium-500m",
    "device": "auto",
    "quantization": "bf16",
    "max_tokens": 2048,
    "temperature": 0.2
  },
  "editor": {
    "auto_format": true,
    "line_length": 100
  }
}

Override via CLI flags:

arche --provider openai --model gpt-4 --temperature 0.1 write "..."

---

About Open Synapse Labs

We build specialized coding models and tools for software engineers. Our models are free and open — download them from Hugging Face and run locally without API keys or rate limits.

We actively develop Arche Code — new features and providers are added regularly.

• 🤗 Hugging Face: opensynapselabs
• 💻 GitHub: OpenSynapseLabs

---

License

Apache License 2.0 — see LICENSE for details.