← bobbyjohnstx.github.io

tinycode

A slim, local-LLM-first AI coding assistant. Runs air-gapped against your own LLMs — Ollama, ramalama, vLLM, or any OpenAI-compatible endpoint. Cloud providers supported as a secondary option.

tinycode / container / operator / homebrew-tap
Install

Three ways to start

Homebrew for local dev. Container for teams. Operator for platform engineering.

Homebrew
$ brew install bobbyjohnstx/tap/tinycode
macOS and Linux
From source
$ git clone && bun install
$ bun dev
Requires Bun
Container
$ curl -fsSL https://raw.githubusercontent.com/bobbyjohnstx/tinycode-container/main/install.sh | sh
podman or docker
First 5 Minutes

Install, run, build something

Four workflows that show what tinycode does in practice. Copy-paste these into your terminal after installing.

Debug a failing test

$ tinycode /path/to/project

# In the TUI, type:
The test in auth_test.go is failing with "token expired."
Find the root cause and fix it.

# Or use the debug skill directly:
/debug auth_test.go is failing with "token expired"

Plan a feature before writing code

# Switch to plan mode — read-only, safe to explore
$ tinycode /path/to/project

# Press Tab to switch to the plan agent, then:
Add a /health endpoint that returns pod name,
uptime, and connected LLM providers.

# tinycode writes a plan to .tinycode/plans/
# Review it, approve, switch to build mode to execute

Review a pull request

$ tinycode /path/to/project

# Ask the code-reviewer agent:
/ask code-reviewer Review the diff on the current branch
against main. Focus on correctness and security.

Explore an unfamiliar codebase

$ tinycode /path/to/new-project

# Ask the architect agent:
/ask architect How is authentication handled in this project?
Trace from the HTTP handler to the token validation.
Terminal UI

The primary interface

The TUI is the fastest way to work. It starts instantly, runs anywhere a terminal does, and keeps you in the same environment as your code. Full-featured interactive session with conversation history, model switching, agent invocation, and inline tool approval.

# Start in the current directory
$ tinycode

# Or point at a specific project
$ tinycode /path/to/project

Modes

  • build (default) — full tool access. Reads, writes, edits files, runs shell commands, executes tools.
  • plan — read-only with hard permission enforcement. The LLM can explore the codebase and write only to a plan file. All other edits are blocked at the tool level.

TUI features

  • Session tree sidebar (<leader>b) — toggleable ASCII tree showing session hierarchy organized by parent-child relationships.
  • Agent switching (Tab or <leader>a) — cycle through agents or pick from a list. Use /ask <agent> for one-shot subagent invocations.
  • Model switching — change models mid-conversation. Auto-discovers Ollama, vLLM, ramalama, and MaaS providers at startup. Warms up local models on startup with tool-call verification.
  • Session export — tinycode export --format html <session-id> exports to self-contained HTML for sharing.

Configuration

# ~/.config/tinycode/config.json
{ "model": "ollama/qwen3.5:9b", "lsp": true }

# Or use ramalama (container-based LLM serving)
$ ramalama serve ollama://qwen3.5:9b
$ export TINYCODE_RAMALAMA_HOST=http://localhost:8080

# Or connect to a LAN model-as-a-service server
$ export TINYCODE_MAAS_HOST=https://your-maas-server
$ export TINYCODE_MAAS_API_KEY=your-key
Web UI & Desktop

Browser and native app

Web UI

SolidJS + TailwindCSS web interface with the same conversation, agent, and tool capabilities as the TUI. Connects to the tinycode API server.

$ tinycode serve    # headless API server
$ tinycode web      # server + web UI → http://localhost:4096

Desktop app

Electron app for macOS, Windows, and Linux. Wraps the web UI in a native window.

  • System tray — menu bar (macOS) or system tray (Windows/Linux) with Show/Hide and Quit.
  • Global hotkey (Cmd/Ctrl+Shift+T) — bring tinycode to front or minimize without closing.
  • Auto-updates — checks GitHub Releases and notifies with an in-app banner.
  • Theme sync — detects OS dark/light mode changes automatically.
  • Platform behaviors — macOS: dock badge for notifications, Cmd+Q to quit. Windows/Linux: taskbar flash on background notifications.
IDE Integration

Agent Client Protocol

tinycode supports the Agent Client Protocol (ACP) for IDE integration. Editors connect to tinycode via stdio.

# Start an ACP server for your editor
$ tinycode acp --cwd /path/to/project
  • VS Code extension — reference extension included at packages/vscode-extension/. See docs/acp-integration.md for building custom integrations.
  • Supported editors — VS Code, Zed, JetBrains (any editor implementing ACP).
Agents & Skills

24 agents, 9 skills

Each agent has per-agent tool permissions — read-only agents get only the tools they need (~4 tools), write agents get edit access (~7 tools). This reduces prompt processing time by 80-90% on local models. Agents with a .compact.md variant automatically use a lighter prompt for models ≤8B parameters.

Built-in agents

architect
Read-only code analysis
debugger
Root-cause analysis
executor
Focused implementation
planner
Strategic work plans
code-reviewer
Severity-rated review
security-reviewer
OWASP Top 10, CVEs
test-engineer
TDD workflows
designer
UI/UX development
cluster-admin
K8s/OpenShift ops
git-master
Atomic commits, rebasing
tracer
Causal tracing
writer
Technical documentation
critic
Quality gate
analyst
Requirements analysis
explore
Fast codebase search
verifier
Completion verification
scientist
Hypothesis-driven research
qa-tester
CLI testing via tmux
code-simplifier
Simplify without changing behavior
document-specialist
External docs & references
workspace
Environment setup
agent-reviewer
Validate agent prompts
skills-reviewer
Validate skill definitions

Skills

Type / to see available commands. Skills inject specialized instructions.

  • /debug — isolate the most likely root cause for a known failure
  • /trace — evidence-driven causal tracing with competing hypotheses
  • /verify — confirm a change works before claiming completion
  • /deepinit — generate per-directory AGENTS.md files across a codebase
  • /ai-slop-cleaner — clean AI-generated code with regression-safe workflow
  • /mcp-setup — configure MCP servers via guided menu
  • /remember — triage session findings across memory surfaces
  • /configure-notifications — set up Telegram, Discord, or Slack notifications
  • /tc-doctor — diagnose tinycode configuration and environment issues (14 checks, pure bash)

CLI commands

  • tinycode plugin-search [query] — search available plugins in the curated registry
  • tinycode plugin <name> — install a plugin (resolves registry names or npm specifiers)

API documentation

When tinycode is running, visit http://localhost:4096/api/docs for interactive API reference (Scalar UI, 114 endpoints). Raw spec at /api/openapi.json.

Container

tinycode-container

github.com/bobbyjohnstx/tinycode-container

OCI container image packaging tinycode with oh-my-tiny, tmux, and git. Built on UBI9, multi-arch (amd64 + arm64), OpenShift arbitrary-UID compatible.

# Run with Ollama on the host network
$ podman run -it --network host \
  -e TINYCODE_SERVER_PASSWORD=changeme \
  quay.io/bjohns/tinycode-container:latest

# With a remote vLLM endpoint
$ podman run -it -p 4096:4096 \
  -e TINYCODE_VLLM_URL=http://your-vllm-server:8000 \
  -e TINYCODE_SERVER_PASSWORD=changeme \
  quay.io/bjohns/tinycode-container:latest

Deploy to OpenShift / Kubernetes

$ kubectl apply -k k8s/base                  # Deployment + Service + Route
$ kubectl apply -k k8s/overlays/ephemeral     # no PVC, testing only
$ kubectl apply -k k8s/overlays/ingress       # vanilla K8s with Ingress

Features

  • GitOps mode — clone a repo on startup via TINYCODE_GIT_REPO, optional auto-pull on restart.
  • vLLM auto-config — set TINYCODE_VLLM_URL to auto-configure endpoint and model.
  • Cluster-admin mode — TINYCODE_CLUSTER_ADMIN=true downloads oc CLI for cluster management.
  • Swarm tool — includes tmux for supervised multi-worker sessions with shared persistence.
  • RHOAI auto-detection — detects Kubernetes environment and disables LSP downloads in air-gapped clusters.
Operator

tinycode-operator

github.com/bobbyjohnstx/tinycode-operator

Kubernetes Operator for OpenShift. Manages TinycodeInstance custom resources with Helm-based reconciliation. Handles Routes, PVCs, SCCs, vLLM auto-probing, and pod lifecycle.

Install the operator

$ git clone https://github.com/bobbyjohnstx/tinycode-operator
$ cd tinycode-operator
$ make push IMAGE_ORG=yourorg IMAGE_TAG=v0.1.0
$ make install OPERATOR_IMAGE=quay.io/yourorg/operator:v0.1.0

Prepare a namespace

$ oc new-project tinycode-dev
$ oc create rolebinding tinycode-operator-admin \
  --clusterrole=admin \
  --serviceaccount=tinycode-operator-system:tinycode-operator-manager \
  -n tinycode-dev
$ oc create secret generic tinycode-password \
  --from-literal=TINYCODE_SERVER_PASSWORD=mysecretpass \
  -n tinycode-dev

Create a TinycodeInstance

apiVersion: tinycode.dev/v1alpha1
kind: TinycodeInstance
metadata:
  name: my-tinycode
spec:
  vllm:
    - name: vllm-qwen3
      url: http://qwen3-30b.qwen3.svc.cluster.local:8080
  model: "vllm-qwen3/qwen3-30b"
  auth:
    passwordSecret: tinycode-password
  storage:
    projectsSize: "20Gi"

Security contexts

  • tinycode-restricted — default. Non-root (UID 1001), all capabilities dropped.
  • tinycode-hostpath — when spec.storage.hostPath is set. Requires cluster-admin approval.
  • tinycode-shell — when spec.shell.enabled: true. Adds hostPID + SYS_PTRACE. Requires review.

Additional capabilities

  • Cross-namespace vLLM discovery — annotate model services with tinycode.dev/discover=vllm, list namespaces in spec.discovery.namespaces.
  • GitOps mode — spec.git.url clones a repo into /projects with optional credentials and auto-pull.
  • Cluster-admin mode — spec.clusterAdmin.enabled mounts kubeconfig and downloads oc CLI.
  • Self-service provisioning — users create their own TinycodeInstance CRs in prepared namespaces. Instance-per-user isolation with no collisions.
  • Vanilla Kubernetes — deploy without the operator using Kustomize manifests from tinycode-container, or Tekton + Argo CD for CI/CD.
Ecosystem

Four projects, one stack

Use whichever level fits your environment.

tinycode
Core server, TUI, web UI, desktop app, agents, skills, tools, and LLM provider integrations.
tinycode-container
OCI container image. UBI9, multi-arch, OpenShift arbitrary-UID compatible. GitOps, vLLM auto-config, cluster-admin mode.
tinycode-operator
Kubernetes Operator for OpenShift. TinycodeInstance CRs, Helm reconciliation, SCCs, Routes, vLLM auto-probing, self-service multi-user.
homebrew-tap
Homebrew formula for brew install bobbyjohnstx/tap/tinycode on macOS and Linux.

Built on opencode by SST. The core architecture — session processor, provider abstraction, tool system, and TUI — originates from the opencode project.