Dev Toolkit

An AI-assisted developer CLI for analyzing errors, explaining and fixing code, generating boilerplate, and getting terminal commands — from your terminal, with your own OpenAI key.

Features

• BYOK-first — bring your own OpenAI key; no account, no server, your code never touches third-party infrastructure beyond OpenAI itself
• Project-aware analysis — optionally include surrounding files as context (gitignore-respecting, credential-file denylist, capped at 50 files / 20KB each)
• Six AI commands — analyze, explain, fix, generate, scaffold, terminal
• Local history — queries are saved to ~/.dev-toolkit/history.json (BYOK mode), or server-side if you run the optional self-hosted server
• Suggestion-only terminal commands — the terminal command prints suggested shell commands; it never executes anything

Installation

npm install -g @mattgraba/dev-toolkit

Verify:

devtk --help

Quick Start (BYOK)

# Set your OpenAI API key (stored locally, owner-only file permissions)
devtk config set-key sk-your-openai-api-key

# Analyze a file
devtk analyze -f ./src/buggy.js -l javascript

Your key is stored at ~/.dev-toolkit/config.json and calls go directly to OpenAI. The OPENAI_API_KEY environment variable takes precedence over the config file if both are set.

CLI Reference

| Command | Description | Key flags | | ---------- | ------------------------------------------------ | ------------------------------- | | config | Manage configuration (set-key, remove-key, show) | — | | analyze | Analyze buggy code → explanation + fix | -f <file> -l <language> | | explain | Plain-English explanation of code | -f <file> -l <language> | | fix | Corrected version of broken code | -f <file> -l <language> -o <out> | | generate | Generate code from a description | -d <description> -o <out> | | scaffold | Scaffold a React component | -n <name> -o <out> | | terminal | Suggest terminal commands for a goal | -g <goal> | | history | View past queries (local file or server) | — | | login | Authenticate with a self-hosted server (optional) | — |

Context-aware mode

devtk analyze -f ./src/index.js -l javascript --context

--context scans nearby .js/.ts/.json files and includes them in the prompt. The scan respects .gitignore, skips dotfiles and credential-shaped filenames (*.pem, *.key, id_rsa*, *credential*, *secret*, …), and is capped at 50 files of up to 20KB each.

Optional: Self-Hosted Server

The repo includes a full backend (Express API with JWT auth, per-user rate limiting, and MongoDB history) and a React web client. There is no public hosted instance — the server exists as a tested, self-hostable reference implementation and a demonstration of the project's backend engineering. If you run your own:

export DEV_TOOLKIT_API_URL=https://your-server.example.com
devtk login
devtk analyze -f ./src/buggy.js -l javascript

See docs/CONFIGURATION.md for server setup. BYOK is the way to use the tool day to day.

| | BYOK | Self-hosted server | |---|---|---| | Account required | No | Yes (on your server) | | OpenAI key | Yours, local | Your server's | | History | Local file | Server + web UI | | Privacy | Key and code stay local (OpenAI only) | Requests pass through your API |

Architecture

BYOK:         CLI ──────────────────────────────▶ OpenAI API

Self-hosted:  CLI ──┐
                    ├──▶ Express API (JWT auth, per-user rate limiting)
        Web client ─┘         │
                              ├──▶ OpenAI API
                              └──▶ MongoDB (users, history)

See docs/ARCHITECTURE.md for the full picture, and docs/RETROSPECTIVE.md for an honest audit of the v1 codebase and what v2 fixed.

Configuration

Config file: ~/.dev-toolkit/config.json (created with owner-only permissions; migrated automatically from ~/.dev-helper/ if you're upgrading).

| Field | Purpose | |-------|---------| | openaiApiKey | Your OpenAI key (BYOK mode) | | model | OpenAI model for BYOK mode (default gpt-4o-mini) — devtk config set-model <model> | | token | JWT from devtk login (self-hosted server mode) | | apiUrl | Your self-hosted server's URL |

Environment variables: OPENAI_API_KEY (overrides config key), DEV_TOOLKIT_MODEL (overrides model), DEV_TOOLKIT_API_URL (overrides API URL).

For self-hosting the server, see docs/CONFIGURATION.md.

Development

npm install          # CLI deps
npm test             # CLI tests
cd server && npm install && npm test   # server tests

Contributing

Pull requests are welcome. Please open an issue first to discuss proposed changes.

License

MIT © Matt Graba