A Ghost in the Terminal: Code Assassin

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

This submission is technically a day late, but in the true spirit of Halloween, nothing stays dead forever. Better late than never.

What I Built

Code Assassin is a speaking, voice-driven coding assistant that runs entirely in your terminal. It started as a workaround: I was building something else and needed text-to-speech, so I piped model output through a local TTS voice. Then I realized the same setup could be useful hands-free coding approach, if the assistant had real access to my environment.

Because it runs locally next to my files, I can give it permission to review, rewrite, and test code and get work done without leaving the terminal or installing an extension. My workspace shrinks to a file directory and one open terminal.

It also has a personality. The system prompt gives the agent a blunt voice, so its commentary and feedback on my code is actually easy to listen to.

Demo

• Sound Demo
• Voice-Driven Workflow: Speak naturally to interact with your code. Speech-to-text is captured locally using Wisper Flow running on my PC for ultra-low latency.

Code

Before, Code Assassin was a "chat wrapper":

user input → context builder (injects @file, --file, --diff context that the *user* selects manually) → Ollama /api/chat streaming → parser splits <speak>/<detail> + fenced code blocks → editor applies fenced diffs with safety (backup, path confinement, no shell)

What I added:

• Self-directed discovery: the model can read files, list directories, and grep/glob the tree mid-conversation instead of waiting for the user to attach context.
• Shell access under policy: commands run through a safety policy: read-only git, pytest, ruff, and lint are auto-approved; everything else requires explicit user confirmation (or --allow-run). Nothing runs silently.
• An agent loop: the model can plan "read X → edit Y → run tests" and the loop keeps going, feeding tool results back into the conversation until the task is done.
• A text-fence tool protocol: `tool type=read path=... fences parsed by an incremental streaming state machine. I tried native Ollama function calling first, but qwen2.5-coder:3b drifts on it; a custom fence protocol is reliable enough for a small model to actually use tools.
• *Safe edits: every write/diff is backed up (undoable), confined to the project root, and diff application is strict: if the model's context lines don't match the file, the edit is rolled back instead of guessed.

Try it

1. Install Ollama (installs as a normal Windows app, runs on 127.0.0.1:11434) and ollama pull qwen2.5-coder:3b
2. Clone the repo, pip install -e ., and make sure assassin is on your global PATH
3. Run assassin doctor to check the backend, then assassin to start the interactive session

Command	What it does
assassin	Interactive voice session
assassin ask "prompt"	One-shot query
assassin doctor	Health checks
assassin voices list	Curated + local TTS voices
assassin bench	Latency/VRAM benchmark
--file, --diff, --staged	Context injection
/task, /voice, /edits, /undo, /status, /run	Slash commands

Notes on model behavior (honest limits)

• qwen2.5-coder:3b edits reliably only when it can see the file contents (/file or --file). Without context, it hallucinates the current lines.
• Diff application is strict: if the model's context lines don't match the file, the edit is refused and rolled bac. That means no silent corruption, at the cost of needing good context.

How I Built It

Code Assassin is built entirely around local, open-weight AI:

• Ollama + qwen2.5-coder:3b for generation. Everything runs on-device, so code and prompts never leave the machine.
• Piper TTS (en_GB-alan-medium) is a local neural TTS, so even audio is generated on-device.
• I created a incremental streaming parser (a state machine tolerant of chunk boundaries and CRLF), a ToolExecutor for read/list/glob/`g

nadinev6 / Code-Assassin

Code Assassin

Overview

Terminal voice-driven coding assistant powered by local Qwen 2.5 Coder 3B and Piper TTS.

Features

• Keyboard input only — no microphone or STT in v1
• GPU LLM — Ollama qwen2.5-coder:3b (4 GB VRAM target)
• CPU TTS — Piper voice en_GB-alan-medium (zero VRAM)
• Dual output — Markdown/code to terminal, short voice summary to speakers
• Autonomous editing — model-proposed changes with safety checks
• Per-project memory — Persistent conversation history
• Package management — Python 3.11+ with uv

Architecture

graph TD
    A[CLI] --> B[Context]
    B --> D[Ollama]
    D --> E[Parser]
    E --> F[Piper]
    E --> H[Terminal]
    I[Editor] --> J[Backups]
    B --> K[Memory]

Loading

Quickstart

Windows

# Clone and setup
cd D:\Projects
uv clone https://github.com/Kilo-Org/Code-Assassin Code-Assassin
cd Code-Assassin
# Setup with default values
powershell scripts\setup.ps1

# Or setup with custom options
powershell scripts\setup.ps1 -ProjectName "qwen2.5-coder:3b"

…

View on GitHub

---

⚠️ AI Code Editing Disclaimer

Code Assassin can autonomously read, patch, and refactor code, but it relies heavily on the capabilities of the underlying model. Because it currently defaults to lightweight local weights (qwen2.5-coder:3b), there are some limitations.