pucky

A tiny coding agent with minimal dependencies 🐤.

If you want to understand the general workflow of a coding agent without too much abstraction and with an easy to read language, then this is for you 🫵.

Otherwise go read codex rust repository.

Dependencies

• google-genai - for LLM calls
• pathspec - for .gitignore files filtering
• pygments - terminal syntax highlighting
• elevenlabs - for text-to-speech (optional, only needed for @tts action)

Requirements

• Python >= 3.10
• Install uv if you don't have it already, follow this

Setup

1. Clone the repository:

git clone https://github.com/Graffioh/pucky.git
cd pucky

2. Create virtual environment:

uv venv

3. Install packages:

uv pip install .

(If you want to experiment while changing the code, then use -e flag)

4. Add pucky to your PATH (add this to your ~/.zshrc or ~/.bashrc) so that you can run it with pucky cmd:

export PATH="$PATH:/path/to/pucky"

And reload your shell:

source ~/.zshrc  # or source ~/.bashrc

5. Create a .env file in the pucky directory with your Google API key (can be obtained here):

echo "GOOGLE_API_KEY=<your_api_key>" > .env

Usage

Run pucky from any directory (it will operate on that directory):

cd /path/to/your/project
pucky

Ask pucky to read/edit/create/remove files, then y to accept / n to decline.

Type quit or q to quit pucky.

Tools

Pucky can use the following tools to interact with your codebase:

• read_file(file_path) - Read the contents of a file
• write_file(file_path, content) - Write content to a file (overwrites entire file)
• edit_file(file_path, patch) - Apply a unified diff patch to a file (efficient for small changes)
• delete_file(file_path) - Delete a file
• create_directory(dir_path) - Create a directory
• execute_bash_command(command) - Execute a bash command
• scan_codebase(root_path) - Scan and show the codebase structure
• grep_search(root_path, query, max_results) - Search for text in the codebase
• update_system_prompt(instruction) - Update the agent's system prompt with a new instruction (can be called by the agent itself)

Actions

While the CLI is running you can execute async local commands prefixed with @ called Actions:

• @file <path_to_file> - read a file and inline its content into the next prompt
• @tree <path_to_dir> - show the file-tree project structure (defaults to current directory)
• @context - print the current context length in tokens
• @tts - speak the latest agent response using elevenlabs text-to-speech
• @prompt <text> - append a custom instruction to the dynamic system prompt
• @show_prompt - display the current system prompt (including dynamic instructions)
• @reset_prompt - clear all dynamic system prompt instructions
• @mode <agent|chat> - switch between agent mode (full capabilities) and chat mode (read-only)
• @help - list all available async commands

You can chain multiple @file commands and then type your actual question. The agent will see every staged file before answering.

Warning

Right now there is no security check for dangerous operations, so be careful, everything is at your own risk!!!.

Feedback

For feedbacks, DM me on X.