Goli-CLI

A TypeScript AI coding agent with an Ink (React) TUI — my college side project. Open-weight-first, npm-workspaces monorepo, published to npm as @goli-cli/cli.

🚧 Active student project – built in my free time while juggling classes. Feedback and bug reports are very welcome, but expect some rough corners.

---

Documentation: CHANGELOG.md · API Reference · Contributing · Security · Agent Guide · Docs Index

---

Goli is an agentic coding assistant I'm building as a personal side project: a terminal UI that plans, edits files, runs shell commands, and iterates on a codebase with an LLM behind it. It's a learning project as much as a tool — every loop of the repo has pushed the TUI, tool sandbox, multi-provider layer, memory, and multi-agent orchestration into something that actually runs.

The default backend is Ollama (ollama/gpt-oss:120b-cloud) — an open-weight model. Point it at a local Ollama server (no key needed) or Ollama Cloud with a free key; the provider layer also adds Anthropic, Gemini, and OpenAI-compatible endpoints without locking you to one vendor.

Status: active-development student side project. Things move, some corners are rough, and I document the honest gaps. The test suite is large because I lean on it to survive my own refactors.

Features

Agent core & providers

• ReAct-style agent loop with systematic planning, tool calling, and per-mode tool filtering (read-only / plan / build / god / local-llms).
• Pluggable multi-provider layer (packages/llm-providers): Ollama (default), Anthropic, Gemini, plus a router. OpenAI is hard-blocked in this build. No mock/demo provider — the loop always talks to a real backend.
• Sandboxed execution — read-only / workspace-write / danger-full-access modes; GOLI_SANDBOX=local|docker; Linux sandboxing via bubblewrap. Path safety + a denylist for destructive commands.
• MCP support — connect external tool servers (goli mcp add/remove/list/scan).
• Memory — session memory, a recursive self-improvement system (SICA), and a skill catalog that extracts reusable skills from successful trajectories (L1/L2 progressive disclosure).
• Multi-agent orchestration — an agent-swarm pipeline (scout → researcher → architect → planner → implementer → debugger → qa → reviewer → documenter) with parallel sub-agents, worktrees, and a shared blackboard.

TUI Features (Ink/React)

• 25 built-in themes (Tokyo Night, Dracula, Solarized, GitHub, Nord, Monokai, Ayu, colorblind-safe variants; WCAG AA contrast across themes) plus user YAML skins in ~/.goli/skins/ — live hot-reload via /theme.
• Vim mode input (INSERT/NORMAL/VISUAL), slash-command autocomplete, @-file and !-shell completion, undo/redo.
• Markdown rendering for agent messages — bold, lists, code blocks, tables, 8 message renderers, 5 spinner styles. Toast notifications for transient state; screen-reader mode and WCAG AA contrast where supported (NO_COLOR aware).
• Persistent input history (~/.goli/history), reverse-search, mouse scroll, dense-tool mode.
• DiffReviewDialog — see the diff before approving edit_file/write_file.

See docs/tui/architecture.md for the component tree and docs/cli/themes.md for the skin catalog.

Slash commands

Mode & review: /help · /mode build|plan|god|safe (+ aliases /plan, /build, /godmode, /safemode) · /tier · /theme · /design · /clear · /compact · /expand · /allowlist Context & memory: /context · /memory · /skills (incl. archive) · /sica · /model · /cost TUI & misc: /vim · /copy · /shortcuts · /stats · /audit · /queue · /bg · /tips · /doctor · /mcp · /quit — plus a few debug helpers (/echo, /btw, /inputmode). Type / in the TUI to auto-complete them. See the "Slash Commands" section of docs/cli/command-reference.md.

Headless / CI

• goli -p "..." — run a prompt and print the result to stdout, exit. Great for scripts/CI.
• goli --local-llms — a three-axis router (sensitivity / complexity / availability) across local Ollama workers + cloud.
• goli doctor — config / provider / sandbox health check.
• goli cron — schedule agent runs.

---

Monorepo layout

npm workspaces + Turborepo; apps/ for interfaces, packages/ for shared libraries.

---

Quick Start

Recommended — Install from npm

Prerequisites: Node.js ≥ 20.18 and npm ≥ 11.

npm install -g @goli-cli/cli
goli --version
goli wakeup

For the default route, run local Ollama (ollama serve, no key) or set OLLAMA_API_KEY for the Ollama Cloud tier; for Anthropic/Gemini set the matching key. Config lives in ~/.goli/config.toml (or env vars — see docs/user/reference/env-vars.md).

From source — Contributors & development

Prerequisites: Node.js ≥ 20.18 and npm ≥ 11 (the repo pins packageManager: npm@11.13.0).

# 1. Clone
git clone https://github.com/Gauravkumar260/Goli-CLI.git
cd goli-cli

# 2. Install + build (Turborepo — packages build in topological order)
npm install
npm run build

# 3. Configure the model backend
cp .env.example .env     # edit keys

For the default route, run local Ollama (ollama serve, no key) or set OLLAMA_API_KEY in .env for the Ollama Cloud tier; for Anthropic/Gemini put the matching key in .env.

# 4. Run
npm run goli -- wakeup            # interactive TUI
npm run goli -- -p 'explain this repo'   # headless, print result
npm run goli -- doctor            # health check
npm run goli -- --version         # print version

.env is not committed (see .gitignore) — secrets stay local.

---

Command reference

Run goli --help for the full flag list. Shell completions (apps/cli/completions/) are available for bash, zsh, and fish.

---

Development

npm run dev          # run CLI in dev (no dist needed)
npm run typecheck    # tsc --noEmit (turbo, all packages)
npm run lint         # eslint . (--max-warnings 0)
npm test             # vitest unit + integration (3342 total, 3338 passing)
npm run verify       # build && lint && typecheck && test

Other useful gates: npm run test:e2e, test:isolated (subprocess-per-test), test:perf, test:memory, test:coverage, plus npm run bench for cold-start metrics. See CONTRIBUTING.md.

Documentation

Goli Studio (experimental)

A browser companion: starts a server-side agent loop with streaming output, tool-call cards, and permission prompts. Still a work in progress — treat it as an extrusion, and the CLI as the well-maintained surface.

npm run studio:db:generate && npm run studio:db:push
npm run studio:runtime & npm run studio:dev   # http://localhost:3000

Roadmap (honest)

• Solidify the evals harness (packages/evals) and SWE-bench-style integration
• Finish SSE/WebSocket MCP transports (currently stdio + HTTP; SSE/WS fall back to HTTP)
• Replace bubblewrap with native Landlock for the Linux sandbox (today landlock.ts wraps bwrap)
• Provider streaming improvements, better context-window budgets
• Whatever breaks during my PhD-free weeknights

Contributing

This is a student side project, so keep expectations low — but small, kind PRs and thoughtful issue reports are welcome. Baseline for any change: npm run build && npm run lint && npm run typecheck && npm test.

License

MIT — see LICENSE. The default backend is open-weight (ollama/gpt-oss:120b-cloud). See AGENTS.md for the codebase pattern/gotcha notes and CODE-MAP.md for the source map.

Status Note

Most of the features described above work at least partially, but not all of them are complete or reliable yet. Some features are ahead of the current implementation.

I'm actively working through these gaps and rough edges. Expect fixes, improvements, and honest corrections as the project evolves.