Arche Code

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

Hugging Face: https://huggingface.co/opensynapselabs
GitHub: https://github.com/OpenSynapseLabs

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 — fine-tuned local models via HuggingFace transformers
• OpenAI — GPT models 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

# Re-run model setup anytime
arche setup

---

Architecture

Provider System (model.py)

from arche_code import ModelConfig, ArcheAgent

# Arche model
config = ModelConfig(provider="arche")
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/model.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
• metadata dict

Task history is 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]

Features:

• Rolling conversation history
• File read commands
• 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

Features:

• Tab completion
• Persistent history
• Interactive command execution

---

Model Setup

First-Run Onboarding

On first launch, arche shell automatically starts the setup wizard if no model is detected.

$ arche shell

No model downloaded yet. Let's get you set up.
Run interactive model setup now? [Y/n]: y

Re-Running Setup

arche setup

Automatic Download During Tasks

arche --provider arche write "hello world in Rust"

If the selected model is missing, Arche Code prompts to download it automatically.

Local Cache Path

~/.arche/models/<model_name>

---

Configuration

Configuration file:

~/.arche_code/config.json

Example:

{
  "model": {
    "provider": "arche",
    "model_name": "default",
    "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 "..."

---

Performance & Memory

8-Bit Quantization

When quantization is set to q8, Arche Code automatically enables 8-bit loading via bitsandbytes.

config = ModelConfig(
    provider="arche",
    quantization="q8",
)

If bitsandbytes is unavailable, the loader falls back automatically.

---

Memory Management in Long Sessions

Arche Code includes built-in memory hygiene for extended sessions:

• Step history cap
• Task history trimming
• Periodic compaction
• Manual compaction via /compact
• Provider reload support

Programmatic compaction:

agent.compact_memory()

---

Changelog

v1.0.1

• First-run onboarding
• arche setup command
• Interactive model picker
• Expanded model catalog
• 8-bit quantization support
• Agent step history cap
• Memory trim optimization

---

About Open Synapse Labs

We build specialized coding models and tools for software engineers.

Our models are open and available on Hugging Face for local use without API keys or rate limits.

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

• Hugging Face: https://huggingface.co/opensynapselabs
• GitHub: https://github.com/OpenSynapseLabs

---

License

Apache License 2.0 — see LICENSE for details.