DumbCode

An interactive and one-shot AI coding assistant for the terminal. DumbCode answers questions, explains and generates code, fixes bugs, refactors, and acts as an agentic coding tool that reads your project, edits files, and runs commands — with auditability and rollback built in.

It runs on Node.js ≥ 18 and Bun, has zero runtime dependencies, and works on Windows, macOS, and Linux.

Highlights
Requirements
Installation
Quick start
Command overview
Interactive chat
Image input
Agentic mode
Hooks
Permissions, modes & approval
Sessions, history & export
Skills, custom commands & project goal
Background agents & subagents
Checkpoints, rewind & blame
Context index
MCP server mode
CI bot & self-update
GitHub bot
Usage ledger & cost control
Configuration
Security model
Troubleshooting
Development & release
Project layout
License

Highlights

Ask, explain, generate, fix, refactor with automatic git context, multi-file attachments, and persistent history.
Agentic loop (on by default): the model drives local tools — reading, searching, editing, testing — in a bounded, audited loop.
Extensible by plain files: skills, custom slash commands, subagents, and a project goal are all markdown in .dumbcode/.
Trustworthy automation: rule-based permissions and modes, pre/post tool-use hooks, per-run checkpoints, and a full provenance ledger with rewind / blame.
Works with any OpenAI-compatible API — 75+ providers, local Ollama, or Shifu — plus streaming, multi-provider fallback, and cost budgets.
Zero dependencies and a self-contained Windows executable.

Requirements

Node.js ≥ 18 (or Bun), or the Windows executable which needs nothing installed.
An API key for the model provider you choose. DumbCode itself has no runtime package dependencies.

Installation

npm (requires Node ≥ 18)

Install the CLI globally from npm:

npm install -g dumbcode
dumbcode --version
dumbcode chat

The npm package is the same codebase as the exe — it runs on Node ≥ 18 with zero runtime dependencies. npm install -g only covers the CLI runtime; it does not include the GitHub App bot (bot/) or the Windows installer — for those, see the GitHub bot section and the Windows exe + setup below.

If npm install -g dumbcode fails with 404 Not Found or E403, the package may not be published yet under that exact name — check the releases page or run from source (next section).

Windows exe + setup

Download dumbcode-setup.exe from the releases page and run it. It fetches the latest dumbcode.exe, installs it to %LOCALAPPDATA%\DumbCode, and offers to add it to your user PATH — no administrator rights required.

Building the executables from source requires Bun (the scripts use Bun.build):

npx --no-install bun scripts/build-exe.mjs          # -> dist/dumbcode.exe
npx --no-install bun scripts/build-exe.mjs --entry=scripts/setup.mjs --outfile=dist/dumbcode-setup.exe

The build stamps the version from package.json and the app icon. Cross-compile for other platforms with --target:

npx --no-install bun scripts/build-exe.mjs --target=bun-linux-x64 --outfile=dist/dumbcode-linux

Installing from the local artifacts (no admin, prompts before touching PATH):

.\dumbcode-setup.bat                                # double-clickable
# or: powershell -ExecutionPolicy Bypass -File install.ps1 [-Dir <path>] [-NoPath] [-Yes]

Uninstall by deleting the folder (and the PATH entry if one was added).

From source

No install step is required — run the entry point directly:

node bin/dumbcode.js --help
node bin/dumbcode.js status
node bin/dumbcode.js chat

With Bun: bun bin/dumbcode.js chat.

Quick start

Point DumbCode at a provider, then ask away.

1. Pick a provider. List presets with dumbcode providers, then configure:

dumbcode config set provider openrouter
dumbcode config set model openai/gpt-4o-mini
dumbcode config set apiKey <your-key>

Any OpenAI-compatible endpoint works — vLLM, LiteLLM, Cloudflare, Bedrock proxies, and 75+ hosted providers:

dumbcode config set provider custom
dumbcode config set baseUrl https://<host>/v1
dumbcode config set model <model-id>
dumbcode config set apiKey <key>

Local models with no key:

dumbcode config set provider ollama
dumbcode config set model qwen2.5-coder
# first: ollama pull qwen2.5-coder

DumbCode also speaks Shifu natively (shifu-fast | shifu-auto | shifu-high); guest use needs no key, and dumbcode shifu login connects your account via SSO (browser approval, auto-refreshing token) or a dashboard key.

2. Check the connection:

dumbcode status

3. Ask something:

dumbcode ask "where is auth handled?"
dumbcode ask "why is this slow?" --file src/index.js
dumbcode chat

No key yet? Preview what would be sent — free and offline:

dumbcode ask "summarize the diff" --dry-run

Keys can be supplied through environment variables instead of config, so they never touch disk:

DUMBCODE_PROVIDER, DUMBCODE_MODEL, DUMBCODE_API_KEY,
DUMBCODE_BASE_URL, DUMBCODE_TEMPERATURE

Vendor fallbacks: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, OLLAMA_HOST.

Command overview

Command	Purpose
`ask "<question>"`	Answer a question with repo + git context attached
`explain <file>`	Explain a file and flag gotchas
`generate "<task>"`	Generate code (`--lang`, `-o <file>`)
`fix <file>`	Fix bugs; `--write` applies the fix
`refactor <file> "<how>"`	Refactor; `--write` applies
`chat`	Interactive REPL (also the default with no arguments)
`config ...`	`show` / `get <k>` / `set <k> <v>` / `path` / `init`
`provider` / `model`	Shortcuts for `config set`
`shifu ...`	`login` / `status` / `logout` (Shifu account)
`providers`	List presets and endpoint guidance
`status`	Provider, model, key, repo, and health overview
`history`	Past interactions (`--limit N`, `--clear`)
`sessions`	List / export / delete saved sessions
`replay <session>`	Re-run a session's turns on another model, side by side
`skills`	List / show / save skills
`commands`	List custom slash commands
`goal`	Show / set / append / clear the project goal
`index`	Build / refresh the context index and search symbols
`agent "<task>"`	Deploy a background agent
`agents`	List / tail / stop background agents
`agents-defs`	List subagent definitions
`undo` / `checkpoints` / `rewind` / `restore` / `blame`	Rollback + provenance
`queue`	Park prompts offline; `--run` replays when back online
`stats`	Usage aggregates (`--share` posts anonymous totals)
`cache`	Response-cache stats (`--clear`)
`mcp`	Serve local tools over MCP (see below)
`completion`	Shell tab-completion (`bash` / `zsh` / `fish`)
`upgrade`	Self-update from GitHub releases (`--check` to inspect first)
`version` / `help`	Print version / usage

Common flags: --file <path> (repeatable), --provider, --model, --api-key, --base-url, --temperature, --max-tokens, --top-p, --config <file>, --no-git, --plan, --yes, --ask, --no-tools, --allow-shell, --no-stream, --dry-run, --verbose, --budget <usd>, --max-steps, --cache, --skill <name> (repeatable), --fallback-provider / --fallback-model / --fallback-base-url / --fallback-api-key.

Interactive chat

dumbcode chat --session work     # named session; auto-saves each turn

A typical session:

dumbcode> /file src/ai.js
dumbcode> why is the timeout 90s?
dumbcode> /diff
dumbcode> /provider ollama
dumbcode> /exit

Slash commands

Command	Action
`/help`	Show command help
`/exit` `/quit`	Leave chat
`/clear`	Forget the conversation and attached files
`/file <path>`	Attach a file to context
`/files` `/unfile`	List / detach attached files
`/diff`	Show the git diff
`/status`	Provider, model, permission mode, repo
`/provider` `/model`	Switch provider / model (saved)
`/dry` `/stream`	Toggle dry-run and streaming
`/tools` `/auto` `/plan` `/mode`	Toggle agent tools, auto-approve, plan mode, permission mode
`/markdown`	Toggle markdown rendering of answers
`/index`	Context index: `status` / `search <sym>` / `rebuild`
`/skills` `/skill [name]`	List / toggle skills; `/skill save <name>` captures the last prompt
`/commands`	List custom slash commands
`/goal`	Project memory: `set` / `append` / `clear` (bare shows)
`/undo` `/checkpoints` `/rewind` `/restore` `/blame`	Rollback + provenance (see below)
`/agents`	List subagent definitions
`/save [name]` `/sessions` `/export [name]`	Persist / list / export the transcript
`/compact`	Summarize older turns into a brief now

Anything else is sent to the model. Exit auto-saves unsaved transcripts, named from your first message and the date.

Streaming. Responses stream by default (SSE where the provider supports it). A host that rejects stream: true falls back to a plain request. Opt out with --no-stream or /stream.

Markdown rendering. In an interactive terminal, answers are rendered with language-tagged code blocks, headings, lists, quotes, inline code, bold, and links. Rendering is display-only — history and exports keep raw markdown — and stays correct while streaming (a code fence split across tokens renders as one block). Toggle with /markdown; force off with --no-markdown. Piped, non-TTY output stays plain by default.

Piped operation. Chat reads piped input, which makes scripting and smoke tests easy:

"/status`n/files`n/exit" | dumbcode chat

Image input

Attach images (PNG/JPG/GIF/WebP, ≤5MB) to any ask or chat turn; they are sent as multimodal content parts to vision-capable models — OpenAI-compatible, Anthropic, Gemini, and Ollama (llava-style) shapes are all converted automatically:

dumbcode ask "what's wrong with this UI?" --file screenshot.png
dumbcode chat            # then: /file diagram.png  and ask about it

Text-only providers and no-image prompts are unaffected — the same request path sends a plain string when there are no images.

Agentic mode

Agentic mode is on by default for ask and chat. The model drives local tools in a loop — reading files, searching, checking git, editing, running commands — until it answers.

dumbcode ask "where is auth handled?"
dumbcode ask "..." --no-tools      # plain answer, no tools
dumbcode ask "..." --ask           # prompt for every shell/edit
dumbcode chat
dumbcode> /tools                   # toggle tools
dumbcode> /auto                    # toggle auto-approve

Tools

Tool	Read-only	Purpose
`read_file`, `list_dir`, `list_files`, `grep`	✓	Project inspection, sandboxed to the project root
`git_status`, `git_diff`, `git_commit`	*	Git state and commits
`fetch_url`, `web_search`	✓	Read a URL (GET only) / search the web
`symbol_find`	✓	Find files that define or reference a symbol (via the context index)
`run_command`, `run_tests`, `lint`		Shell commands, guarded as below
`edit_file`		Exact-block replace or create, with diff preview and automatic backup
`todo_write`, `todo_read`	✓	Live multi-step checklist
`goal_read`, `goal_update`		Read / maintain the project goal memory
`dispatch_agent`	✓	Run a defined subagent
`deploy_agent`		Deploy a detached background agent

Loop bounds. The loop is deliberately bounded: a step cap (--max-steps, default 8 for one-shots and 12 in chat), a repeat-call breaker, and a ~100 KB cumulative tool-output budget. Past the budget it stops reading and finalizes rather than growing the request until the provider rejects it.

Multi-step work gets a live checklist the model maintains with todo_write / todo_read, rendered after each tool round and restored when a --session resumes.

Hooks

Hooks run configured shell commands around tool calls and prompts. Configure them in ~/.dumbcode/config.json:

"hooks": {
  "PreToolUse": [{ "matcher": "edit_file", "command": "npx eslint --fix $FILE" }],
  "PostToolUse": [{ "matcher": "run_command", "command": "notify-send done" }],
  "UserPromptSubmit": [{ "command": "secret-scan < /dev/stdin" }],
  "SessionStart": [{ "command": "echo starting" }]
}

A matcher is a tool name, * wildcard, or /regex/. Each event arrives as JSON on stdin, plus $TOOL_NAME, $TOOL_ARGS_JSON, and $FILE environment variables. A failing PreToolUse hook blocks the call and its stderr is fed back to the model; all other hooks only log to the audit trail.

Permissions, modes & approval

Beyond the ask/auto binary, DumbCode supports rule-based permissions and persistent modes, checked before every non-read-only tool call in chat, one-shot runs, subagents, and MCP alike:

"permissionMode": "default",
"permissions": [
  { "tool": "edit_file",   "pattern": "src/**", "action": "allow" },
  { "tool": "run_command", "pattern": "rm*",    "action": "deny" }
]

Modes. default (ask) · plan (read-only) · acceptEdits (edits run, shell still asks) · bypassPermissions (like --yes — deny rules still apply). Override per run with --plan / --yes / --ask, in chat with /plan and /mode <m>, or persistently via config set permissionMode.

Rules. The first matching rule wins. tool is a tool name or *; pattern matches a path glob (src/** nests, src/* does not) or, for shell commands, a substring of the command. allow skips approval, ask forces a prompt, and deny blocks the call outright — deny overrides everything, including --yes.

Shell safety. Shell commands pass an allowlist (shellAllowlist in config), destructive-pattern blocks (rm -rf /, fork bombs, …), and per-command approval unless auto-approve is on. Child processes never see DumbCode's provider keys (see Security model).

Sessions, history & export

dumbcode chat --session work                 # resume or create; auto-saves each turn
dumbcode sessions                            # list saved sessions
dumbcode sessions delete work
dumbcode sessions export work -o work.md     # shareable transcript, secrets redacted
dumbcode chat --compact-at 40                # auto-summarize turns past N messages (0 = off)
dumbcode ask "..." --cache                   # reuse identical plain answers locally
dumbcode cache                               # cache stats

Long chats compact automatically: older turns fold into a short brief via one extra model call — use /save first to keep the full transcript. --cache applies to plain answers only; tool results are never cached.

Replay and merge. dumbcode replay <session> --model <m> re-runs a saved session's turns on another provider/model for side-by-side comparison. dumbcode sessions graft a b merges two transcripts into one session.

Offline queue and budgets. dumbcode queue "<task>" parks a prompt when you're offline or rate-limited (it also auto-parks on network failure); queue --run replays parked prompts oldest-first. --budget <usd> stops the agent loop once spending passes the limit (priced from a models.dev snapshot).

Skills, custom commands & project goal

Everything below is plain markdown, so teams can commit these files to the repo and share them.

Skills

Skills are composible instruction packs with frontmatter:

dumbcode skills                          # list (built-in + yours)
dumbcode skills show test-driven
dumbcode skills save <name> -d <desc>    # body from stdin or --from <file>
dumbcode ask "..." --skill test-driven   # repeatable
# in chat: /skills  /skill  /skill save <name> [desc]

Drop skills in <project>/.dumbcode/skills/ (team) or ~/.dumbcode/skills/ (personal; project wins on name clash). Built-ins ship with test-driven, perf-audit, and docs-writer. Chat suggests matching skills as you type and remembers active ones per session. When a prompt works particularly well, save it as a skill — triggers phrases will auto-suggest it later.

Custom slash commands

A markdown file in <project>/.dumbcode/commands/<name>.md (or ~/.dumbcode/commands/) becomes /name:

---
description: Review the diff, focus on auth.
---
Review the current diff. Focus on: {args}

{args} is substituted with the arguments typed after the command name; without it, arguments are appended to the body. Built-in commands always win on name clash. List with dumbcode commands or /commands.

Project goal

dumbcode goal set <text> (or /goal set, /goal append, /goal clear; bare to show) writes <project>/.dumbcode/goal.md — a team-shared, live memory committed with the repo. The goal is appended to every system prompt, and the model keeps it current during a session through the goal_read / goal_update tools (approval-gated like any write).

Background agents & subagents

Background agents run detached from your terminal, tools on, with approvals delegated at deploy time:

dumbcode agent "upgrade the deps and run tests"
dumbcode agents               # list + status
dumbcode agents log <id>      # tail output
dumbcode agents kill <id>

Each agent saves a session (agent-<id>) you can resume or export later. Teams split one goal across children: dumbcode agent "<goal>" --split "frontend, backend, tests" fans out a child per part, and dumbcode agents merge <team> synthesizes the finished children into one answer.

Subagents are in-session agents with isolated context — different from detached background agents. Define them in <project>/.dumbcode/agents/<name>.md (frontmatter: description, optional tools subset, model, maxSteps), list with dumbcode agents-defs or /agents, and let the model call them via dispatch_agent(name, task) — only the verdict returns to the parent loop. A read-only reviewer ships by default. The model can also deploy detached agents mid-loop via deploy_agent(task) (approval-gated like shell).

Checkpoints, rewind & blame

Every agent run — a chat turn, one-shot ask, subagent, or background agent — opens a checkpoint. Every edit_file replace snapshots the file before writing and every create is recorded, all tagged with who ran it. That gives per-run rollback and a full blame trail:

dumbcode checkpoints           # list runs: id, time, who, files changed
dumbcode rewind <id>           # roll all files back to that run's start
dumbcode restore <id>          # roll back a single snapshot
dumbcode blame src/app.js      # who touched it, how it was approved
dumbcode undo [--list]         # restore just the last agent edit

The same commands are available in chat as /undo, /checkpoints, /rewind, /restore, and /blame. rewind restores each file edited after the checkpoint to its content at that point (agent-created files are deleted) and prunes those edits from the ledger; backup files stay on disk. The audit log keeps the full record — every tool call carries who (session/agent/subagent), the permission decision, whether it was approved, and its checkpoint. Shell side effects are not tracked; checkpoints cover agent edit_file operations.

Context index

A per-project fingerprint and symbol index (stored outside the repo in ~/.dumbcode/indexes/) makes symbol lookup cheap and sessions change-aware:

dumbcode index                 # build if needed + show what changed since
dumbcode index rebuild
dumbcode index search <name>   # which files define or reference a symbol
# in chat: /index [status|search <sym>|rebuild]

The symbol_find tool lets the agent answer "where is X defined?" by returning candidate files instead of grepping the whole tree (node_modules, binaries, and dotfiles are skipped). Freshness checks are stat-only (size + mtime), so they stay cheap on large repositories, and chat warns at startup when files changed since the last build.

MCP server mode

Serve DumbCode's local tools to MCP clients (Claude Desktop/Code, Cursor, and other MCP hosts) over stdio:

dumbcode mcp --yes     # approvals delegated to the client
dumbcode mcp --plan    # read-only: write tools refuse

It speaks MCP protocol 2024-11-05 (initialize, tools/list, tools/call) and exposes all local tools — read/search/git/edit/shell/todo/ goal — subject to the same permission rules: an allow rule runs without client approval, a deny rule blocks even with --yes, and permissionMode: "bypassPermissions" behaves like mcp --yes. Without --yes, shell and edit calls fail closed (denied (no terminal to approve in)) and the client is expected to act as the approval layer. mcp --plan stays read-only regardless of rules.

Claude Desktop example (claude_desktop_config.json):

{ "mcpServers": { "dumbcode": {
  "command": "node",
  "args": ["<path-to-DumbCode>/bin/dumbcode.js", "mcp", "--yes"],
  "cwd": "<your project dir>"
} } }

CI bot & self-update

Use DumbCode as a review bot in any repository's GitHub Actions workflow with zero setup (Node 20+):

- uses: Shimba-crypto/DumbCode@v0.12.3
  with:
    task: review this diff for bugs and security smells
    provider: openai
    api-key: ${{ secrets.OPENAI_API_KEY }}
    args: --plan

Self-update from GitHub releases:

dumbcode upgrade --check   # report latest vs yours, change nothing
dumbcode upgrade           # download and swap (Windows finishes after exit)

GitHub bot

Beyond one-shot Actions runs, DumbCode ships a full GitHub App bot in bot/ — a zero-dependency webhook server that makes comments summon the agent, like a teammate on call in your repos:

@dumbcode why is the login test flaky?   → read-only answer as a comment
@dumbcode review                         → PR review verdict (SHIP/FIX/BLOCK)
@dumbcode fix <thing>                    → fix + new PR (opt-in, BOT_ALLOW_FIX)

The server verifies X-Hub-Signature-256, checks out the PR head, and runs the same in-process agent loop as the CLI (runAgentLoop) tagged who: github-bot:<owner>/<repo>#<n>, so permissions, hooks, checkpoints and blame behave exactly like a local run. Runs are read-only by default; fix is gated behind BOT_ALLOW_FIX=1 and a shell allowlist. Works with a plain GH_TOKEN for local testing or full GitHub App auth (GH_APP_ID + GH_PRIVATE_KEY).

The bot server lives in bot/ and is not part of the npm CLI package — to run it, clone this repo and:

cd DumbCode
npm install                        # dev deps only (icon stamp, tests)
npm run bot:setup -- --org DumbestBOT   # one-command GitHub App registration → bot/.env
npm run bot                               # start on :4310  (GET /health, POST /webhook)

(These are repo npm scripts, not an npm install -g target. The published npm package is the CLI only.)

Full setup, GitHub App permissions, the environment table, and security notes: bot/README.md and bot/.env.example.

Usage ledger & cost control

Every AI call appends one line to ~/.dumbcode/usage.jsonl. dumbcode status summarizes the current month's calls, tokens, and estimated cost across providers; dumbcode stats shows local aggregates. Answers end with an estimated token count (real counts when the provider reports usage) plus a cost estimate for known models.

Configuration

Configuration lives in ~/.dumbcode/config.json (override the file with --config <path> or DUMBCODE_CONFIG).

Key	Default	Purpose
`provider`	`openai`	Provider preset (`providers` lists them)
`model`	`gpt-4o-mini`	Model id
`apiKey`	—	API key (or use env vars; never printed in full)
`baseUrl`	—	Custom OpenAI-compatible endpoint
`temperature` / `maxTokens` / `topP`	`0.2` / `0` / `0`	Sampling (0 = provider default)
`shellAllowlist`	`[]`	Only these binaries may run via tools (empty = unrestricted)
`permissionMode`	`default`	One of `default` / `plan` / `acceptEdits` / `bypassPermissions`
`permissions`	`[]`	Allow/ask/deny rules (see above)
`hooks`	`{}`	Hook commands per event
`fallbacks`	`[]`	`[{provider, model?, …}]` tried in order on retryable errors

Per-project presets. ./.dumbcoderc.json in the working directory overrides the global config (model, tools, approvals, prompts).

Project instructions. ./DUMBCODE.md (or ./.dumbcodeprompt) is appended to every system prompt automatically.

Data files (all under ~/.dumbcode/): config.json, history.jsonl, audit.log, backups/ (edit snapshots + manifest), sessions/, indexes/, skills/, commands/, usage.jsonl, queue.jsonl, cache.jsonl. Each location can be redirected with DUMBCODE_* environment variables for portable setups and CI.

Shell completion:

dumbcode completion bash >> ~/.bashrc    # bash, zsh, or fish

Security model

Read this before using --yes, MCP, or publishing output.

Keys live in one place: ~/.dumbcode/config.json or environment variables. Never paste that file into chats, issues, or screenshots. status and config print masked keys, and history/audit files store redacted text.
Tools are sandboxed to the project directory — .. escapes are refused. Shell runs through an allowlist (shellAllowlist), destructive-pattern blocks (rm -rf /, fork bombs, …), and per-command approval unless auto-approve is enabled.
Untrusted content is fenced. Output from file reads, greps, shell, tests, and web tools is wrapped in <<<UNTRUSTED CONTENT>>> markers, and the system prompt instructs the model to treat anything inside as data — not instructions — so prompt injection in a repo file or web page can't steer the agent. Suspicious patterns ("ignore previous instructions", fake tool-call syntax, secret-exfil requests) are flagged on the console when they appear in tool output, and the GitHub bot wraps issue/PR text the same way.
Child processes cannot see DumbCode's provider keys (DUMBCODE_API_KEY, OPENAI_*, SHIFU_*, … are stripped from tool-spawned environments). Third-party tokens such as GITHUB_TOKEN are left alone so tools like gh keep working.
--yes / MCP --yes means the client approves — use it only when the calling application shows you each tool call (Claude and Cursor do). --plan stays read-only even with --yes, and permission deny rules override both.
SSO login uses a state nonce and a 127.0.0.1-only callback — the dumbcode shifu login URL is safe to click only from your own terminal.
fetch_url is GET-only (http/https) — it cannot POST your files anywhere.
Found a hole? Open an issue — please don't post exploit details publicly.

Troubleshooting

Symptom	Fix
`No API key`	`dumbcode config set apiKey <key>` or set `DUMBCODE_API_KEY`
`HTTP 401`	Wrong or revoked key — regenerate from the URL shown by `dumbcode providers`
`HTTP 404`	Wrong model name or `--base-url` — check preset values
`Cannot reach …`	Offline, server down, or wrong `--base-url`; is Ollama running? (`ollama serve`)
`timed out`	Provider is slow — retry; a local model may still be loading on first run

Development & release

npm test                    # 95 unit tests (node --test), hermetic, no network
npm run smoke               # help + providers + status

Releasing a new version:

Bump "version" in package.json (the single source of truth — builds stamp it into the executables).
Run npm test; update test/ and this README as needed.
Build the executables and checksums (requires Bun):

npx --no-install bun scripts/build-exe.mjs
npx --no-install bun scripts/build-exe.mjs --entry=scripts/setup.mjs --outfile=dist/dumbcode-setup.exe
sha256sum dist/dumbcode.exe dist/dumbcode-setup.exe > dist/SHA256SUMS.txt

Commit, tag (git tag -a v<version>), and push. Publish a GitHub Release with the dist/ artifacts:

gh release create v<version> dist/dumbcode.exe dist/dumbcode-setup.exe dist/SHA256SUMS.txt

Publish the npm package (same version, CLI only — files in package.json keeps test/, bot/, and scripts/ out of the tarball):

npm whoami                    # must be a publish-capable account
npm publish --access public

CI runs the test suite on Ubuntu and Windows across Node 20 and 22.

Project layout

bin/dumbcode.js   entry point (node + bun compatible)
scripts/          build-exe.mjs (Bun.compile + icon), setup.mjs (installer entry)
src/
  index.js        CLI router / argument parsing / help
  commands.js     command implementations
  chat.js         interactive REPL (slash commands, streaming, rendering)
  ai.js           provider client + fallback chain
  tools.js        agent tools + bounded ReAct loop
  permissions.js  rule-based permissions + modes
  hooks.js        Pre/PostToolUse + prompt/session hooks
  todo.js         live task checklist
  subagents.js    in-session subagent runner (dispatch_agent)
  agents.js       detached background agents + teams
  ledger.js       checkpoints / rewind / restore / blame
  context.js      project context index (symbol_find)
  goal.js         project goal memory (.dumbcode/goal.md)
  skills.js       skill discovery / save
  slashcmds.js    custom slash commands
  md.js           zero-dependency markdown → ANSI renderer
  mcp.js          MCP server (JSON-RPC stdio)
  sessions.js     session persistence
  export.js       session → shareable markdown (redacted)
  history.js      history + audit log + edit backups
  usage.js        usage ledger + cost
  queue.js        offline prompt queue
  cache.js        opt-in response cache
  upgrade.js      self-update from GitHub releases
  shifu.js        Shifu SSO / API-key auth
  providers.js    presets + custom endpoint resolution
  config.js       config + env / --config / project overrides
  files.js        file context + code extraction
  git.js          git-aware context
  prompts.js      system prompts + project instructions
  ui.js           colors / spinner / confirm / redaction
  prices.json     models.dev price snapshot
skills/           built-in skills (test-driven, perf-audit, docs-writer)
assets/           app icon
test/             unit tests (node --test, incl. test/bot.test.js)
action.yml        GitHub Actions review-bot action
bot/              GitHub App bot (webhook server + engine + GitHub helpers)

License

MIT — see LICENSE.

Navigation Menu

Repository files navigation

DumbCode

Table of Contents

Highlights

Requirements

Installation

npm (requires Node ≥ 18)

Windows exe + setup

From source

Quick start

Command overview

Interactive chat

Image input

Agentic mode

Hooks

Permissions, modes & approval

Sessions, history & export

Skills, custom commands & project goal

Skills

Custom slash commands

Project goal

Background agents & subagents

Checkpoints, rewind & blame

Context index

MCP server mode

CI bot & self-update

GitHub bot

Usage ledger & cost control

Configuration

Security model

Troubleshooting

Development & release

Project layout

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.dumbcode/agents		.dumbcode/agents
.github/workflows		.github/workflows
assets		assets
bin		bin
bot		bot
scripts		scripts
skills		skills
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
dumbcode-setup.bat		dumbcode-setup.bat
install.ps1		install.ps1
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

DumbCode

Table of Contents

Highlights

Requirements

Installation

npm (requires Node ≥ 18)

Windows exe + setup

From source

Quick start

Command overview

Interactive chat

Image input

Agentic mode

Hooks

Permissions, modes & approval

Sessions, history & export

Skills, custom commands & project goal

Skills

Custom slash commands

Project goal

Background agents & subagents

Checkpoints, rewind & blame

Context index

MCP server mode

CI bot & self-update

GitHub bot

Usage ledger & cost control

Configuration

Security model

Troubleshooting

Development & release

Project layout

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages