José Almeida
47ff0804a5
* feat(cli): add --port flag as the user-facing port knob
Introduces --port (and KANDEV_PORT) as the primary, command-aware port
flag: in start/run it sets the Go backend port (the proxy front door
the browser actually hits), and in dev it sets the Next dev server port.
--backend-port and --web-port still work but emit a one-time stderr
deprecation note pointing at --port and --web-internal-port respectively.
* feat(cli): print labelled "open:" URL on startup
Replaces the ambiguous "[kandev] url:" / "ready at" lines with a
labelled block that always shows the user-facing URL first, plus the
backend (api) and web (internal) URLs when they differ. Each command
now declares its own publicUrl: backend in start/run (where the Go
server reverse-proxies Next.js), web in dev (browser hits Next direct).
* style(cli): apply prettier formatting to args.test.ts
* refactor(cli): tighten arg parsing per review feedback
- Validate value-taking flags (--port, --backend-port, --web-internal-port,
--web-port, --version) and reject missing/non-numeric values with a clear
ParseError instead of leaking NaN into the port validator.
- Drop the test-only _resetWarnedFlagsForTest export and the module-level
warned-flag set; parseArgs now returns deduped deprecatedFlags and cli.ts
emits warnings command-aware (e.g. --backend-port → KANDEV_BACKEND_PORT
in dev, where --port maps to web).
- Stop double-printing the "open:" URL: logStartupInfo now lists labelled
backend (api) / web (internal) URLs only, leaving the post-readiness
open: line as the single source of truth.
- Fix help text: --web-internal-port works in dev too.
- Drop multi-line JSDoc blocks per CLAUDE.md style guide.
* fix(cli): validate env-var ports and collapse comment to one-liner
Catches non-numeric KANDEV_PORT / KANDEV_BACKEND_PORT / KANDEV_WEB_PORT in
envPort with a clear ParseError instead of letting NaN reach
ensureValidPort. Drops a multi-line comment per CLAUDE.md style.
* fix(cli): reject non-integer port values
Number.isFinite accepts floats like 3000.5 which then fail downstream
in ensureValidPort with a generic message. Tighten parsePort and
envPort to require integers and add float tests for both flag and
env-var paths.
* fix(cli): reject out-of-range port values with flag-named errors
Adds 1-65535 range checks to parsePort and envPort so values like 0,
-1, or 65536 fail with a flag/env-var-named ParseError instead of
reaching ensureValidPort with a generic 'backend port' label.
* test(cli): cover KANDEV_WEB_PORT happy path and range validation
* test(cli): cover KANDEV_WEB_PORT in run/start mode too
* fix(cli): explicit CLI flag wins over env var for port resolution
Previously KANDEV_BACKEND_PORT silently overrode --port because each
process port resolved its own env var before the generic --port
fallback. New precedence per process: explicit CLI flag > generic
--port flag > explicit env var > generic KANDEV_PORT. Also relabel
the startup info from "backend (api)" / "web (internal)" to plain
"backend" / "web" — "internal" was misleading in dev where the web
URL is what users open.
* style(cli): collapse resolvePorts comment to one line
* fix(cli): reject empty --version= and empty port env vars
- --version= (no value after =) now throws ParseError instead of
silently storing the empty string as the version tag.
- envPort distinguishes unset (undefined) from empty (""); an empty
KANDEV_PORT / KANDEV_BACKEND_PORT / KANDEV_WEB_PORT is now treated
as misconfiguration and fails fast.
* refactor(cli): make --port a plain alias for --backend-port
Drops the command-aware split where --port mapped to web in dev and
backend in run/start. --port and --backend-port now both set
options.backendPort regardless of command, and KANDEV_PORT is a plain
fallback for KANDEV_BACKEND_PORT. The whole point of the original
fix was that the *backend port* is the URL users actually open in
run/start (because the Go server reverse-proxies Next.js); a single
flag that always means "the backend port" matches that mental model
without per-command surprises.
Removes deprecationReplacement and the command-aware warning logic
since the two flags are now interchangeable. --web-port → --web-internal-port
deprecation stays.
* test(cli): re-add KANDEV_WEB_PORT run-mode coverage dropped in refactor
Kandev
Manage tasks. Orchestrate agents. Review changes. Ship value.
Quick Start
npx kandev
Downloads the latest release, starts the backend + web app, and opens your browser. Data (worktrees, SQLite DB) is stored in ~/.kandev by default.
Version and Updates
npx kandev(run mode) uses the latest GitHub release bundle by default.- At startup, the launcher prints the resolved release tag (for example:
[kandev] release: v0.2.3 (github latest)). - Use
--version <tag>to pin a specific runtime bundle release. - CLI package updates are checked from npm and shown as a prompt. They are not forced.
What You Get
- Multi-agent support - Claude Code, Codex, GitHub Copilot, Gemini CLI, Amp, Auggie, OpenCode
- Integrated workspace - Terminal, code editor with LSP, git changes, browser preview, and chat
- Kanban & pipeline views - Organize tasks with opinionated workflows and gates
- CLI passthrough - Drop into raw agent TUI mode for full terminal access
- Workspace isolation - Git worktrees prevent concurrent agents from conflicting
- Session management - Resume and review agent conversations
Supported Agents
| Agent | Default Model | Protocol |
|---|---|---|
| Claude Code | Sonnet 4.5 | stream-json |
| Codex | GPT-5.2 Codex | Codex |
| GitHub Copilot | GPT-4.1 | Copilot SDK |
| Gemini CLI | Gemini 3 Flash | ACP |
| Amp | Smart Mode | stream-json |
| Auggie | Sonnet 4.5 | ACP |
| OpenCode | GPT-5 Nano | REST/SSE |
Beta - Under active development. Expect rough edges and breaking changes.
Requirements
- Node.js (for
npx) - Git
- Docker (optional - needed for container runtimes)
Platforms
- macOS (Intel + Apple Silicon)
- Linux (x64)
- Windows (x64, WSL)
Learn More
Open source, multi-provider, no telemetry, not tied to any cloud.
See the GitHub repository for architecture, vision, development setup, and contributing guidelines.