| --- |
| 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. |
|
|
