--- license: mit language: - en pipeline_tag: text-generation library_name: cpp tags: - creative-writing - ollama - code-execution - productivity - offline-ai - local-llm --- # Pencilclaw v1.0 (Testing) ✏️ ``` ██████╗ ███████╗███╗ ██╗ ██████╗██╗██╗ ██████╗██╗ █████╗ ██╗ ██╗ ██╔══██╗██╔════╝████╗ ██║██╔════╝██║██║ ██╔════╝██║ ██╔══██╗██║ ██║ ██████╔╝█████╗ ██╔██╗ ██║██║ ██║██║ ██║ ██║ ███████║██║ █╗ ██║ ██╔═══╝ ██╔══╝ ██║╚██╗██║██║ ██║██║ ██║ ██║ ██╔══██║██║███╗██║ ██║ ███████╗██║ ╚████║╚██████╗██║███████╗╚██████╗██████╗██║ ██║╚███╔███╔╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ ╚═════╝╚═╝╚══════╝ ╚═════╝╚═════╝╚═╝ ╚═╝ ╚══╝╚══╝ ``` **PENCILCLAW** is a C++ command-line tool that turns your local [Ollama](https://ollama.com/) instance into a creative writing partner with the ability to execute generated C++ code. It follows a simple ADA-style command interface - perfect for writers, tinkerers, and AI enthusiasts who want to keep their data private and their workflows offline. --- ## Features - **Story & Poem Generation** - Use `/STORY` or `/POEM` with a title/subject to get creative text from your local LLM. - **Book Continuation** - The `/BOOK` command appends new chapters to a running `book.txt`, maintaining context from previous content. - **Code Execution** - If the AI responds with a C++ code block (triple backticks), `/EXECUTE` compiles and runs it - ideal for prototyping or exploring AI-generated algorithms. - **Session Logging** - All interactions are saved in `pencil_data/session.log` for later reference. - **Workspace Isolation** - Everything lives in the `./pencil_data/` folder; temporary files are cleaned up after execution. - **Security Awareness** - Includes filename sanitisation and a confirmation prompt before running any AI-generated code. --- ## Project Structure All necessary files for PENCILCLAW are contained within the `/home/kali/pencilclaw/` directory. Below is the complete tree: ``` /home/kali/pencilclaw/ ├── pencilclaw.cpp # Main program source ├── pencil_utils.hpp # Workspace and template helpers ├── pencilclaw # Compiled executable (after build) └── pencil_data/ # **Created automatically on first run** ├── session.log # Full interaction log ├── book.txt # Accumulated book chapters ├── temp_code.cpp # Temporary source file (deleted after execution) ├── temp_code # Temporary executable (deleted after execution) └── [story/poem files] # Individual .txt files for each /STORY or /POEM ``` **The `pencil_data` directory is created automatically when you run the program. All generated content and logs reside there.** --- ## Requirements - **libcurl** development libraries - **cJSON** library - **Ollama** installed and running - A model pulled in Ollama (default: `qwen2.5:0.5b` - change in source if desired) --- ## Installation ### 1. Install System Dependencies ```bash sudo apt update sudo apt install -y build-essential libcurl4-openssl-dev ``` ### 2. Install cJSON If your distribution does not provide a package, build from source: ```bash git clone https://github.com/DaveGamble/cJSON.git cd cJSON mkdir build && cd build cmake .. make sudo make install sudo ldconfig cd ../.. ``` ### 3. Install Ollama ```bash curl -fsSL https://ollama.com/install.sh | sh ollama serve & # start the service ollama pull qwen2.5:0.5b # or another model of your choice ``` ## Custom Models Edit line 36 of the pencilclaw.cpp file: ``` // Model name – change this to match your installed model (e.g., "llama3", "qwen2.5", "mistral") const std::string MODEL_NAME = "qwen2.5:0.5b"; ``` ### 4. Compile PENCILCLAW Place the source files in the same directory and compile: ```bash g++ -std=c++17 -o pencilclaw pencilclaw.cpp -lcurl -lcjson ``` If cJSON headers are in a non-standard location (e.g., `/usr/local/include/cjson`), add the appropriate `-I` flag: ```bash g++ -std=c++17 -o pencilclaw pencilclaw.cpp -lcurl -lcjson -I/usr/local/include/cjson ``` --- ## Usage Start the program: ```bash ./pencilclaw ``` You will see the `>` prompt. Commands are case-sensitive and start with `/`. ### Available Commands | Command | Description | |-------------------|-----------------------------------------------------------------------------| | `/HELP` | Show this help message. | | `/STORY ` | Generate a short story with the given title. Saved as `<title>.txt`. | | `/POEM <subject>` | Compose a poem about the subject. Saved as `<subject>.txt`. | | `/BOOK <chapter>` | Append a new chapter to `book.txt` (creates file if it doesn't exist). | | `/EXECUTE` | Compile and run the first C++ code block from the last AI response. | | `/DEBUG` | Toggle verbose debug output (shows JSON requests/responses). | | `/EXIT` | Quit the program. | Any line not starting with `/` is sent directly to Ollama as a free prompt; the response is displayed and logged. --- ## Security Notes - **Code execution is a powerful feature.** PENCILCLAW asks for confirmation before running any AI-generated code. Always review the code if you are unsure. - **Filename sanitisation** prevents path traversal attacks (e.g., `../../etc/passwd` becomes `____etc_passwd`). - All operations are confined to the `pencil_data` subdirectory; no system-wide changes are made. --- ## Customisation - **Model**: Change the `MODEL_NAME` constant in `pencilclaw.cpp` to use a different Ollama model. - **Prompts**: Edit the templates in `pencil_utils.hpp` (`get_template` function) to adjust the AI's behaviour. - **Timeout**: The default HTTP timeout is 60 seconds. Adjust `CURLOPT_TIMEOUT` in the source if needed. --- ## Troubleshooting | Problem | Solution | |----------------------------------|----------------------------------------------------------------| | `cJSON.h: No such file or directory` | Install cJSON or add the correct `-I` flag during compilation. | | `curl failed: Timeout was reached` | Ensure Ollama is running (`ollama serve`) and the model is pulled. | | Model not found | Run `ollama pull <model_name>` (e.g., `qwen2.5:0.5b`). | | 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.