README.md

---
license: mit
language:
- en
- cpp
library_name: pencilclaw
tags:
- c++
- ollama
- code-generation
- autonomous-agent
- local-ai
- git
- offline
- cpp
- agent
- task-automation
- llm
- code-execution
- self-hosted
- privacy-focused
---



# ✏️ PENCILCLAW – Autonomous C++ Coding Agent (v1.0 Testing)

```
██████╗ ███████╗███╗   ██╗ ██████╗██╗██╗     ██████╗██╗      █████╗ ██╗    ██╗
██╔══██╗██╔════╝████╗  ██║██╔════╝██║██║    ██╔════╝██║     ██╔══██╗██║    ██║
██████╔╝█████╗  ██╔██╗ ██║██║     ██║██║    ██║     ██║     ███████║██║ █╗ ██║
██╔═══╝ ██╔══╝  ██║╚██╗██║██║     ██║██║    ██║     ██║     ██╔══██║██║███╗██║
██║     ███████╗██║ ╚████║╚██████╗██║███████╗╚██████╗██████╗██║  ██║╚███╔███╔╝
╚═╝     ╚══════╝╚═╝  ╚═══╝ ╚═════╝╚═╝╚══════╝ ╚═════╝╚═════╝╚═╝  ╚═╝ ╚══╝╚══╝ 
```

**PENCILCLAW** is a C++‑based autonomous coding agent harness for your local [Ollama](https://ollama.com/) instance to generate, manage, and execute C++ code. It features a persistent task system, Git integration, and a secure execution environment – all running offline with complete privacy.

---

## Features

- **Code Generation (`/CODE`)** – Generate C++ code for any idea, automatically saved as a `.txt` file.
- **Autonomous Tasks (`/TASK`)** – Start a long‑running coding goal; the agent continues working on it in the background via heartbeat.
- **Task Management** – View status (`/TASK_STATUS`) and stop tasks (`/STOP_TASK`).
- **Code Execution (`/EXECUTE`)** – Compile and run the last generated code block (with safety confirmation).
- **Git Integration** – Every saved file is automatically committed to a local Git repository inside `pencil_data/`.
- **Heartbeat & Keep‑Alive** – Keeps the Ollama model loaded and continues active tasks periodically.
- **Secure by Design** – Command injection prevented, path sanitisation, explicit confirmation before running AI‑generated code.
- **Natural Language Interface** – Commands like *"write code for a fibonacci function"* are understood.

---

## Project Structure

```
/home/kali/pencilclaw/
├── pencilclaw.cpp          # Main program source
├── pencil_utils.hpp        # Workspace utilities
├── pencilclaw              # Compiled executable
**└── pencil_data/            # Created automatically on first run**
    ├── session.log         # Full interaction log
    ├── .git/               # Local Git repository (if initialised)
    ├── tasks/              # Autonomous task folders
    │   └── 20260309_123456_build_calculator/
    │       ├── description.txt
    │       ├── log.txt
    │       ├── iteration_1.txt
    │       └── ...
    └── [code files].txt    # Files saved via /CODE or natural language
```

---

## Requirements

- **Compiler** with C++17 support (g++ 7+ or clang 5+)
- **libcurl** development libraries
- **nlohmann/json** (header‑only JSON library)
- **Ollama** installed and running
- A model pulled in Ollama (default: `qwen2.5:0.5b` – configurable via environment variable `OLLAMA_MODEL`)

*Note: PENCILCLAW uses POSIX system calls (`fork`, `pipe`, `execvp`). It runs on Linux, macOS, and Windows Subsystem for Linux (WSL).*

---

## Installation

### 1. Install System Dependencies
```bash
sudo apt update
sudo apt install -y build-essential libcurl4-openssl-dev
```

### 2. Install nlohmann/json
The library is header‑only; simply download `json.hpp` and place it in your include path, or install via package manager:
```bash
sudo apt install -y nlohmann-json3-dev
```

### 3. Install Ollama
```bash
curl -fsSL https://ollama.com/install.sh | sh
ollama serve &   # start the service
ollama pull qwen2.5:0.5b   # or your preferred model
```

Set Model (Optional)

Override the default model by setting the environment variable:
```bash
export OLLAMA_MODEL="llama3.2:latest"
```
### 4. cd
```bash
cd ~/pencilclaw/      -The folder you have the files installed
```

### 5. Compile PENCILCLAW
```bash
g++ -std=c++17 -o pencilclaw pencilclaw.cpp -lcurl
```
If `json.hpp` is in a non‑standard location, add the appropriate `-I` flag.

---

## Usage

Start the program:
```bash
./pencilclaw
```

You will see the `>` prompt. Commands are case‑sensitive and start with `/`. Any line not starting with `/` is treated as natural language and passed to Ollama.

### Available Commands

| Command               | Description                                                                 |
|-----------------------|-----------------------------------------------------------------------------|
| `/HELP`               | Show this help message.                                                     |
| `/CODE <idea>`        | Generate C++ code for the given idea; saved as `<sanitized_idea>.txt`.      |
| `/TASK <description>` | Start a new autonomous coding task (creates a timestamped folder).         |
| `/TASK_STATUS`        | Show the current active task, its folder, and iteration count.             |
| `/STOP_TASK`          | Clear the active task (does not delete existing task files).               |
| `/EXECUTE`            | Compile and run the first C++ code block from the last AI output.          |
| `/FILES`              | List all saved `.txt` files and task folders.                              |
| `/DEBUG`              | Toggle verbose debug output (shows JSON requests/responses).               |
| `/EXIT`               | Quit the program.                                                           |

### Natural Language Examples

- `write code for a fibonacci function`
- `start a task to build a calculator`
- `save it as mycode.txt` (after code generation)

---

## Git Integration

PENCILCLAW automatically initialises a Git repository inside `pencil_data/` on first run. Every file saved via `/CODE` or task iteration is committed with a descriptive message. The repository is configured with a local identity (`pencilclaw@local` / `PencilClaw`) so commits work even without global Git configuration.

If you prefer not to use Git, simply remove the `.git` folder from `pencil_data/` – PENCILCLAW will detect its absence and skip all Git operations.

---

## Security Notes

- **Code execution is potentially dangerous.** PENCILCLAW always shows the code and requires you to type `yes` before running it.
- **Path traversal is prevented** – filenames are sanitised, and all writes are confined to `pencil_data/`.
- **No shell commands are used** – all external commands (`git`, `g++`) are invoked via `fork`+`execvp` with argument vectors, eliminating command injection risks.

---

## Configuration

| Setting                | Method                                                                 |
|------------------------|------------------------------------------------------------------------|
| Ollama model           | Environment variable `OLLAMA_MODEL` (default: `qwen2.5:0.5b`)         |
| Workspace directory    | Environment variable `PENCIL_DATA` (default: `./pencil_data/`)        |
| Heartbeat interval     | Edit `HEARTBEAT_INTERVAL` in source (default 120 seconds)             |
| Keep‑alive interval    | Edit `KEEP_ALIVE_INTERVAL` in source (default 120 seconds)            |

---

## Troubleshooting

| Problem                          | Solution                                                       |
|----------------------------------|----------------------------------------------------------------|
| `json.hpp: No such file or directory` | Install nlohmann/json or add the correct `-I` flag.          |
| `curl failed: Couldn't connect to server` | Ensure Ollama is running (`ollama serve`) and the URL `http://localhost:11434` is accessible. |
| Model not found                  | Run `ollama pull <model_name>` (e.g., `qwen2.5:0.5b`).        |
| Git commit fails                 | The repository already has a local identity; this should not happen. If it does, run `git config` manually in `pencil_data/`. |
| Compilation errors (C++17)       | Use a compiler that supports `-std=c++17` (g++ 7+ or clang 5+). |

---

## License

This project is released under the MIT License. Built with C++ and Ollama.