CodeNova

IDE-embedded AI assistants (Cursor, Copilot) are powerful but tied to the editor. Developers often need to interrogate or modify a codebase from the terminal — in a client repo, on a server, or across multiple folders — without opening a full IDE session. Generic curl to chat APIs cannot read files, list directories, or stage edits safely. Most CLI experiments either auto-write to disk (dangerous) or only chat about code without tool use (hallucination-prone).

The gap is a **workspace-first** terminal agent: point at any absolute path, explore with read-only tools, plan multi-step goals, implement with file/shell mutations — but only after explicit human approval. Power users also want optional remote control (phone/Telegram) and resilient billing when API credits run low, not stack traces that kill the session.

Solo Developer & Product Owner — I designed and built CodeNova end-to-end: Bun/TypeScript CLI entry, matrix-green terminal UI (boot/shutdown animations, command hub, session banners), three AI modes (Ask, Plan, Agent), Vercel AI SDK tool loops with staging and approval flows, OpenRouter/xAI provider layer with 402 retry logic, workspace session management, optional Telegraf Telegram bot (owner-only), Agent Playground example service, env validation scripts, and documentation (README, cheat sheet, per-folder READMEs).

CodeNova is a **Bun 1.1+** monorepo with a clear folder layout: terminal/ (banner, theme, boot-sequence, shutdown-sequence, startup-menu, work-status), modes/ (ask, agent, plan, telegram, interactive-menu), providers/ (model-config, generate-with-retry, ai-errors), and config/ (branding, workspace path, notes export dir). Entry is index.ts via Commander → bun run start.

1$   Terminal  (Bun + TypeScript)
2$        │
3$        ▼
4$ ┌────────────── CodeNova CLI ──────────────┐
5$ │  Ask    read-only repo Q&A               │
6$ │  Plan   goal ─▶ steps ─▶ execute         │
7$ │  Agent  staged edits + shell             │
8$ │         every write needs approval       │
9$ └────────┬──────────────────────┬──────────┘
10$          │                      │
11$          ▼                      ▼
12$   Vercel AI SDK            Telegraf
13$          │                 (optional Telegram uplink)
14$          ▼
15$   OpenRouter  ──▶  models

**Startup flow:** figlet CODE NOVA banner → matrix rain + boot spinner → target directory prompt (config/workspace.ts) → command hub ([1] CLI_SHELL, [2] TELEGRAM_UPLINK, [3] SET_TARGET, [0] DISCONNECT). The install directory is never auto-selected as workspace — every session explicitly chooses the project folder.

**Ask mode** (modes/ask/): read-only orchestrator using Vercel AI SDK ToolLoopAgent with tools read_file, list_files, search_files, analyze_codebase, optional Cursor-style skills (SKILLS_DIRS), and optional Firecrawl web tools. Instructions require tool use before answering; replies match the user's language. Optional export appends to .md inside the workspace or notes/.

**Agent mode** (modes/agent/): mutation tools (create_file, modify_file, delete_file, create_folder, run_shell, etc.) stage all changes in memory. runApprovalFlow() lets the user approve all, review one-by-one with diffs, or cancel. applyApprovedFromTracker() writes only approved paths under the workspace root; shell commands are separate approval groups.

**Plan mode** (modes/plan/): generates a JSON plan (1–15 steps), user multiselects steps, each runs an Agent-style loop with the same approval model, then a final apply pass.

**Providers:** default OpenRouter (OPENROUTER_API_KEY, OPENROUTER_DEFAULT_MODEL); alternate direct xAI (AI_PROVIDER=xai). Deprecated Gemini 2.0 IDs map silently to 2.5. On **402 insufficient credits**, generate-with-retry.ts retries once with a lower max_tokens parsed from the error instead of crashing.

**Telegram** (modes/telegram/): Telegraf bot gated by TELEGRAM_OWNER_ID; /ask, /agent, /plan, /workspace, plain text defaults to Ask. Long replies use plain text to avoid Markdown entity breaks on paths with underscores. Ctrl+C gracefully severs uplink and returns to the hub.

**Agent Playground** (examples/agent-playground/): Bun HTTP API + dashboard on port 3847 for safe practice without touching production repos.

CodeNova targets developers who want **Cursor-like capabilities in any folder** from the terminal — freelancers switching client repos, students practicing on the bundled Agent Playground, or maintainers who prefer CLI over IDE panels. Positioning: **Ask · Plan · Agent** with human-in-the-loop safety, not 'autonomous agent that rm -rf's your project.'

Distribution is GitHub-first (open repo, bun run demo for instant visual hook, cheat sheet for copy-paste). The matrix boot sequence in the screenshot is a strong portfolio differentiator vs generic chat CLIs. Comparable products include Aider, OpenHands CLI, and IDE agents — CodeNova's wedge is polished TUI + three distinct modes + Telegram uplink + workspace picker on every launch.

Monetization is indirect (portfolio, consulting, future hosted team workspaces); the OSS core builds trust. Enterprise angle later: shared approval policies, audit logs of staged commands, and org-wide model routing.

Shipped open-source CodeNova at github.com/subhm2004/CodeNova (TypeScript 100%, Bun). Live capabilities: Ask/Plan/Agent modes, staged file and shell approvals with diff review, workspace targeting via prompt/flag/env/Telegram /workspace, OpenRouter + xAI providers, 402 credit retry, optional owner-only Telegram bot, matrix boot/shutdown animations, session status banner, Agent Playground on :3847, bun run check-env and bun run demo, and structured docs (modes/README.md, providers/README.md, terminal/README.md, cheat sheet). CLI tagline: inject into any directory — ask, plan, agent.

Streaming token output in the terminal would make long Agent answers feel responsive. A proper OS-level sandbox (containers or Landlock) would strengthen shell approval beyond path confinement. TURN-free mesh is fine for Telegram text, but rich code blocks might need chunked delivery or a web dashboard. I'd add plugin hooks for custom tools per workspace (e.g. run tests, lint) without forking core. Publishing to npm/bun registry as codenova global binary would lower install friction beyond git clone.