Code68 is an independent, modular open-source terminal AI coding agent inspired by Claude Code.
The Core Concept:
Cloud Intelligence + Local Execution = Code68
The heavy LLM (e.g.,
Qwen/Qwen2.5-Coder-7B-Instruct, 4-bit quantized) runs remotely on a GPU server (such as a free Kaggle instance with 2x NVIDIA Tesla T4 GPUs), while Code68 runs locally on the developer's computer. The local agent interacts with your real project files, terminal, Git repository, and tests with full security sandboxing and granular permissions. The local computer never needs to load the model into memory.
CLOUD (Remote GPU / Kaggle / vLLM)
┌──────────────────────────────────────────────────┐
│ Qwen2.5-Coder-7B-Instruct (4-bit BitsAndBytes) │
│ OpenAI-Compatible FastAPI Server │
│ Token Auth + SSE Streaming │
└────────────────────────┬─────────────────────────┘
▲ Encrypted Tunnel
│ (Cloudflare / ngrok)
▼
LOCAL DEVELOPER MACHINE ┌──────────────────────────────────────────────────┐
│ Code68 CLI │
│ ┌─────────────────────────────────────────────┐ │
│ │ Autonomous Agent Loop │ │
│ │ (Tool Calling, Loop Detector, Context) │ │
│ └──────────────┬──────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Security & Sandbox Gate │ │
│ │ (Permission Levels, Traversal Guard, Audit)│ │
│ └──────────────┬──────────────────────────────┘ │
│ │ Approved Actions │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Local Tools │ │
│ │ • Filesystem (read, write, edit with diff) │ │
│ │ • Search (ripgrep / python fallback) │ │
│ │ • Terminal (sandboxed commands & timeouts) │ │
│ │ • Git (status, diff, branch, safe commit) │ │
│ │ • Testing (pytest, linters, type checkers) │ │
│ └─────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
- Real Tool-Calling Agent Loop: Autonomous multi-step problem solving, loop detection, and structured tool recovery.
- Surgical Code Editing: Uses unified diffs and snippet replacement rather than blindly rewriting entire files.
- Deep Codebase Intelligence: AST symbol extraction, language discovery,
.gitignorefiltering, and smart token budgeting. - Strict Security & Boundaries:
- Traversal prevention (
resolve_safe_pathconfines access to project root). - 5 Granular permission levels:
read-only,edit-approved,auto-edit,command-approved, andfull-auto. - Destructive command interceptor (
rm -rf, disk wipes, fork bombs blocked). - Secret & API key redaction in logs and tool results.
- Full audit logging in
.code68/audit.log.
- Traversal prevention (
- Provider Agnostic: Seamlessly swap between Kaggle, vLLM, Ollama, OpenRouter, or OpenAI without changing any client code.
- Beautiful Rich Terminal UI: Markdown formatting, syntax highlighting, diff visualizer, and streaming token output.
Any developer with Python 3.11+ can install Code68 as a system-wide or user tool:
# Using pip
pip install git+https://github.com/PRN-6/code68.git
# Or isolated using pipx (recommended for CLI apps)
pipx install git+https://github.com/PRN-6/code68.gitNow code68 is available everywhere in your terminal:
code68 --version# Clone the repository
git clone https://github.com/PRN-6/code68.git
cd code68
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .\.venv\Scripts\activate
# Install in editable mode with development dependencies
pip install -e ".[dev]"Code68 needs an LLM endpoint. Users can choose any of the following options:
- Open a new Kaggle notebook: kaggle.com/code
- Settings (right panel): Accelerator = GPU T4 x 2, Internet = ON
- Paste and run this single cell:
!git clone https://github.com/PRN-6/code68.git %cd /kaggle/working/code68 !pip install -q -r server/requirements-server.txt !python server/kaggle_server.py
- Copy the printed tunnel URL into your
.envfile:CODE68_BASE_URL=https://random-name.trycloudflare.com/v1 CODE68_API_KEY=code68-secret-key
If a user already has Ollama installed locally:
ollama run qwen2.5-coder:7bThen configure Code68:
CODE68_BASE_URL=http://localhost:11434/v1
CODE68_MODEL=qwen2.5-coder:7bCode68 works with any OpenAI-compatible provider:
CODE68_BASE_URL=https://openrouter.ai/api/v1
CODE68_API_KEY=your-openrouter-key
CODE68_MODEL=qwen/qwen-2.5-coder-32b-instructConfigure via environment variables or .env:
CODE68_BASE_URL=https://your-cloud-endpoint/v1
CODE68_API_KEY=code68-secret-key
CODE68_MODEL=Qwen/Qwen2.5-Coder-7B-Instruct
CODE68_PROVIDER=openai-compatible
CODE68_PERMISSION_LEVEL=edit-approvedOr configure via the CLI:
code68 config --set-url "https://your-endpoint/v1" --set-key "your-key"Check system diagnostics:
code68 doctorcode68Inside the interactive session:
- Type your instructions naturally:
Find bugs in auth.py and fix them - Interactive slash commands:
/help- Show available commands/clear- Clear conversation context/compact- Compact message history to stay within token budget/model [name]- View or switch model/status- Check server connection & workspace state/diff- View current uncommitted git diff/undo- Revert changes/exit- Exit Code68
code68 "Analyze the architecture of this project and summarize main entrypoints"Configure safety constraints with CODE68_PERMISSION_LEVEL:
| Level | Allowed Without Prompting | Requires Confirmation |
|---|---|---|
read-only |
File reads, directory listing, searching, git status | File modifications, terminal commands, deletions |
edit-approved (Default) |
Reads, searches, git status | File edits, file deletions, commands |
auto-edit |
File edits, reads, searches | Terminal commands, deletions |
command-approved |
Edits, reads, searches | Terminal commands |
full-auto |
All operations within workspace | None (unattended automation) |
Note: Destructive commands (e.g. rm -rf /, mkfs) and deletions are always flagged regardless of permission level.
Run the full automated test suite (mocked provider, tools, security, indexing, and CLI):
pytest -vcode68/
│
├── pyproject.toml # Package specifications & entry points
├── requirements.txt # Dependency specifications
├── README.md # Complete documentation
├── LICENSE # MIT License
├── .env.example # Sample environment configuration
│
├── server/ # Cloud Inference Server
│ ├── kaggle_server.py # 4-bit Qwen2.5-Coder server with Cloudflare tunnel
│ └── README.md # Kaggle deployment guide
│
├── src/code68/
│ ├── __init__.py
│ ├── main.py # Executable entrypoint
│ ├── cli.py # Typer CLI & interactive REPL
│ │
│ ├── core/ # Agent Architecture
│ │ ├── agent.py # High-level coordinator
│ │ ├── agent_loop.py # Tool-calling agent loop with loop detection
│ │ ├── context.py # Dynamic workspace context builder
│ │ ├── conversation.py # Conversation thread & token manager
│ │ ├── planner.py # Multi-step task planner
│ │ ├── state.py # Agent state & repetitive loop detector
│ │ └── prompts.py # System prompt & behavioral principles
│ │
│ ├── llm/ # Remote Inference Layer
│ │ ├── base.py # Abstract base provider & exceptions
│ │ ├── client.py # Provider factory
│ │ ├── models.py # Message, ToolCall, FunctionCall models
│ │ ├── providers.py # OpenAI-compatible & Mock providers
│ │ └── streaming.py # SSE chunk accumulator
│ │
│ ├── tools/ # Local Execution Tools
│ │ ├── registry.py # Tool registry, permission dispatcher & audit logger
│ │ ├── schemas.py # OpenAI function schema generator
│ │ ├── filesystem.py # Safe read, write, edit_file (diff), list, delete
│ │ ├── search.py # ripgrep integration with Python regex fallback
│ │ ├── terminal.py # Subprocess runner with timeouts & safety filters
│ │ ├── git.py # Git status, diff, log, show, safe commit
│ │ └── testing.py # Automated test, linter, & type checker runner
│ │
│ ├── indexing/ # Codebase Intelligence
│ │ ├── ignore.py # .gitignore filter
│ │ ├── scanner.py # Project & language detection
│ │ ├── symbols.py # Python AST symbol extractor
│ │ └── retrieval.py # Visual ASCII tree & relevant file finder
│ │
│ ├── security/ # Security & Sandboxing
│ │ ├── permissions.py # Granular permission levels
│ │ ├── sandbox.py # Workspace boundary & traversal guard
│ │ └── validation.py # Destructive command detector & secret masking
│ │
│ ├── storage/ # State & Persistence
│ │ ├── config.py # Pydantic configuration loader
│ │ ├── history.py # Conversation history & context compactor
│ │ └── sessions.py # Session persistence to disk
│ │
│ └── ui/ # Terminal Interface
│ ├── terminal.py # Terminal UI coordinator
│ ├── renderer.py # Rich markdown, diffs, panels, & status
│ └── components.py # Approval dialogs & user prompts
│
└── tests/ # Automated Test Suite (27 tests)
├── conftest.py # Fixtures (workspace & mock LLM)
├── test_agent.py # End-to-end tool calling & agent loop tests
├── test_cli.py # CLI commands tests
├── test_indexing.py # Codebase scanner, symbols, & tree tests
├── test_llm.py # LLM provider, streaming, & schema tests
├── test_security.py # Sandbox traversal & permission tests
└── test_tools.py # Filesystem, search, terminal, & git tests
MIT License. See LICENSE for details.