ViCode
In ProgressViCode is a terminal-native AI coding agent published to npm that replaces jump-straight-to-code behaviour with a structured three-mode workflow. In Discuss it asks clarifying questions and pokes holes in your requirements; in Plan it turns the conversation into a concrete, reviewable set of steps and trade-offs; in Build it executes only the approved plan, making targeted edits and verifying its changes where possible. The CLI is written in TypeScript and rendered with Ink, so the whole experience lives inside the terminal it is installed into. It reads the host project before writing anything, mimics existing conventions instead of assuming a framework, never commits, pushes, or amends without an explicit request, and loads specialised skills (reviews, triage, prototyping) on demand.
Why I Built This
Most coding agents start editing files before the problem is even understood, which makes it easy to lose control of scope and direction. I wanted a tool that behaves like a thought partner first and a code generator second — one where nothing gets implemented until I have explicitly approved a plan, and where the output stays concise because it is meant to be read in a terminal.
Role
Solo Developer
Duration
2 months
Status
In Progress
Tech Stack
Key Features
- Mode-driven workflow — explicitly switch between Discuss, Plan, and Build to set intent before any code is written
- Plan-first execution that blocks implementation until you approve the plan, keeping scope and direction under your control
- Repo-aware context: reads the existing codebase and mirrors its style, patterns, and utilities instead of assuming a framework or dependency
- Git-safe by default — never commits, pushes, or amends without an explicit request
- Concise, terminal-first output with reasoning surfaced only when it matters
- Skill-extensible architecture that loads specialised skills (reviews, triage, prototyping) on demand
- Distributed as a global npm CLI, so it runs inside any project directory with a single command
Challenges & Solutions
- Modelling the three modes as an explicit state machine so the agent cannot silently drift from discussing to editing, and so the Build step can only act on an approved plan
- Giving the agent enough repository context to mimic existing conventions without blowing up the prompt or making assumptions about frameworks
- Building a responsive terminal UI with Ink — streaming output, input handling, and confirmations — while keeping the render loop cheap enough to stay snappy
- Enforcing the git-safety guarantee at the tool layer rather than relying on the model to remember not to commit or push
What I Learned
- Designing agent workflows around explicit user approval rather than autonomous execution
- Building interactive terminal interfaces with Ink and React, including streaming state and keyboard-driven prompts
- Packaging and publishing a TypeScript CLI to npm with a working global bin entrypoint