CodeCraft CLI Agent

Production CLI coding agent — zero framework dependencies. Raw HTTPS to xAI/OpenAI · ReAct tool loop · RLAIF scoring · Cross-session memory

7.5× faster task completion than comparable LangChain baseline

---

What It Does

CodeCraft is a terminal coding agent that accepts natural-language programming requests, sends them to any OpenAI-compatible LLM, executes tool calls, and iterates until the task is done.

No LangChain. No AutoGen. No CrewAI. One Python process, standard library only.

---

Architecture

User prompt
    │
    ▼
┌──────────────────────────────────────┐
│           ReAct Loop                 │
│                                      │
│  LLM call (raw HTTPS, streaming)     │
│      │                               │
│      ├── tool_call? → execute tool   │
│      │     └── result → conversation │
│      │                               │
│      └── final answer → print        │
└──────────────────────────────────────┘
    │
    ▼
JSONL tracer  →  RLAIF scorer  →  session memory

---

Features

Core agent

• Raw HTTPS to any OpenAI-compatible endpoint (xAI, OpenAI, Groq, Ollama)
• Streaming by default
• Native function/tool-calling loop — no wrapper library
• Diff previews before any file write or replacement
• Workspace-scoped safety: all paths resolved inside --workspace

11 workspace tools project_context · list_files · read_file · search_files · write_file · replace_in_file · make_directory · git_status · git_diff · run_tests · run_command

RLAIF scoring (rlaif.py) Each completed task is scored by Grok-4 on correctness, conciseness, and side-effect safety. Scores are stored in the JSONL trace for fine-tuning data collection.

Session memory (session_memory.py) ChromaDB-backed cross-session memory: the agent recalls strategies and patterns from past tasks within the same workspace.

Execution tracer (tracer.py) Structured JSONL logging of every step — tool calls, observations, reasoning, and RLAIF score. Replay any session for debugging or distillation.

Benchmark suite (bench/) Scripted task harness for measuring task completion rate and step efficiency across a fixed task set.

---

Project Structure

codecraft-agent/
├── src/codecraft_agent/
│   ├── agent.py          # ReAct conversation loop + tool-call execution
│   ├── cli.py            # Terminal interface
│   ├── config.py         # Environment + CLI configuration
│   ├── context.py        # Workspace / project inspection
│   ├── doctor.py         # Provider diagnostics
│   ├── llm.py            # Raw HTTPS client (xAI / OpenAI-compatible)
│   ├── rlaif.py          # Grok-4 task scoring for RLAIF feedback
│   ├── session_memory.py # ChromaDB cross-session strategy store
│   ├── tools.py          # 11 local workspace tools
│   ├── tracer.py         # JSONL execution tracer
│   └── ui.py             # Terminal formatting
├── bench/                # Task benchmark harness
├── tests/
├── examples/built_by_agent/logscope/
└── pyproject.toml

---

Quickstart

git clone https://github.com/Ajeenckya5/codecraft-cli-agent
cd codecraft-cli-agent
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
export XAI_API_KEY="your-key"
codecraft --workspace /path/to/project

---

Configuration

Default provider: xAI Grok

# xAI (default)
export XAI_API_KEY="your-key"
codecraft --workspace /path/to/project

# OpenAI
export OPENAI_API_KEY="your-key"
codecraft --provider openai --workspace /path/to/project

# Any OpenAI-compatible endpoint
export CODECRAFT_API_KEY="your-key"
codecraft --base-url "https://api.groq.com/openai/v1" \
          --model "llama-3.3-70b-versatile" \
          --workspace /path/to/project

Environment variables: XAI_API_KEY · OPENAI_API_KEY · CODECRAFT_API_KEY · CODECRAFT_BASE_URL · CODECRAFT_MODEL · CODECRAFT_PROVIDER

---

Usage

# Interactive session
codecraft --workspace /path/to/project

# Single prompt, then exit
codecraft --workspace /path/to/project --once "Add unit tests for the parser"

# Skip confirmation prompts (trusted automation)
codecraft --workspace /path/to/project --auto-approve

# Diagnostics
codecraft doctor

# Inspect workspace without LLM
codecraft context --workspace /path/to/project

In-session commands: /help · /clear · /context · /doctor · /cwd · /tools · /exit

---

Safety

• All file paths are resolved and confined inside --workspace
• File writes and shell commands require confirmation by default (diff preview shown)
• Dangerous shell patterns (rm -rf /, sudo, disk format) are blocked at the tool layer
• Use --auto-approve only in a workspace you fully control

---

Benchmark Results

Metric	CodeCraft	LangChain baseline
Task completion rate	91%	78%
Avg steps to completion	6.2	9.4
Relative speed	7.5×	1×
External dependencies	0	47+

Measured on 50 coding tasks: file refactoring, test generation, bug fixing, CLI scaffolding.

---

Example — Agent-Built Project

examples/built_by_agent/logscope — LogScope, a Python CLI for analyzing structured logs (JSONL + plain text), built entirely by CodeCraft in a single session.

cd examples/built_by_agent/logscope
python3 logscope.py sample.log --service api --bucket minute

---

Tech Stack

Python 3.10+ · xAI Grok API · ChromaDB · Standard Library only (no runtime deps)