convez.ai
AgenteDevOps & InfraestruturaIntermediário
djadmin

devkit

djadmin/devkit

Organize todos os localhost que sua IA cria em um painel único

Ver no GitHub
InicialPluginScore · de 0 a 100

CLI que organiza e controla todas as aplicações web locais que sua IA constrói. Transforma portas localhost fragmentadas em URLs nomeadas e estáveis (.localhost), gerencia ciclo de vida e permite registro automático de agentes. Ideal para quem trabalha com múltiplos projetos simultâneos gerados por Claude, Cursor ou Codex.

Instalação

$npx convez-ai djadmin/devkit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.4.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerenciar múltiplas aplicações web locais criadas por agentes de IA
  • Criar URLs nomeadas e estáveis para substituir portas localhost fragmentadas
  • Automatizar registro e controle de lifecycle (start/stop/restart) de apps
  • Recuperar e rastrear aplicações já rodando em localhost

Veredito

devkit resolve um problema real de desenvolvedores que usam agentes de IA: organizar o caos de portas localhost. A integração automática com Claude, Cursor e Codex é bem pensada. Ferramenta prática, sem overhead, com foco em produtividade local.

README

A tradução para o português deste README ainda está na fila.

devkit

The home for every local app your AI builds.

If Claude, Cursor, or Codex keeps leaving you with a pile of forgotten localhost ports, devkit turns those apps into named projects you can route, reopen, and control from one place.

localhost:4839   →   notes.localhost
localhost:3000   →   dashboard.localhost
localhost:5173   →   api-tester.localhost

Install

brew tap djadmin/tap
brew install devkit
devkit bootstrap

The Mac app (menu bar + full window) is available separately at djadmin.github.io/devkit.


Wire Your AI Agent (do this first)

Add one snippet to your agent's global config. Every app it builds after that registers itself automatically — no extra steps.

Claude Code — add to ~/.claude/CLAUDE.md:

## devkit — App Registration
After creating any local web app or service:
  devkit register <slug> --port <port> --cmd "<start-cmd>"
  devkit start <slug>

OpenAI Codex — add to ~/.codex/AGENTS.md:

## devkit — App Registration
After creating any local web app or service:
  devkit register <slug> --port <port> --cmd "<start-cmd>"

Cursor — add to .cursor/rules/devkit.mdc:

---
alwaysApply: true
---
After creating any web app:
  devkit register <slug> --port <port> --cmd "<start-cmd>"

Windsurf — add to .windsurf/rules/devkit.md with the same content as Cursor.


Track Apps You Already Have Running

# Track without taking over lifecycle
devkit register atlas --port 7780 --managed-by external

# Track and let devkit own start/stop
devkit register notes --path ~/code/notes --port 4010 --cmd "npm run dev -- --port 4010"
devkit start notes

Find apps you forgot to register

devkit scan looks for web apps already listening on localhost that aren't in the registry yet — useful when another tool started something with a raw npm run dev and a bare localhost:5173. It detects only HTTP/HTML services (databases and JSON-only APIs are skipped), suggests a name from the page title, and best-effort recovers the start command so you can register it as managed or external.

devkit scan          # human-readable table of unregistered web apps
devkit scan --json   # machine-readable (used by the menu bar app's "Scan Now")

See docs/scan.md for detection details, tuning, and the menu bar integration contract.


Daily Commands

CommandWhat it does
devkit listSee every registered app and its status
devkit start <name>Start a devkit-managed app
devkit stop <name>Stop a devkit-managed app
devkit restart <name>Restart safely
devkit start-allBring everything back after a reboot
devkit stop-allStop all devkit-managed apps
devkit open <name>Open in browser
devkit edit <name>Jump into the project directory with Claude Code
devkit logs <name>Tail the log file
devkit show <name>Print full stored metadata
devkit scanFind running web apps not yet registered
devkit rename <old> <new>Rename a running app safely
devkit update <name>Update port, cmd, path, or description
devkit remove <name>Deregister an app

Browse everything at http://dash.localhost.


How Lifecycle Works

  • devkit-managed: register with --cmd. devkit owns start, stop, logs, pid files, and restart safety.
  • external: register with --managed-by external. devkit tracks name, URL, and status — does not supervise the process.

Crash Recovery (opt-in)

By default devkit starts an app and steps back — if the app later dies, it stays down until you start it again. Opt a devkit-managed app into automatic recovery with a restart policy:

devkit register api --port 3000 --cmd "npm start" --restart on-failure
# or change it later:
devkit update api --restart on-failure        # policies: no (default) | on-failure | always

Then install the background supervisor once:

devkit supervise install      # installs a launchd agent that watches your apps
devkit supervise status       # list supervised apps + agent state
devkit supervise uninstall    # remove it

How it behaves:

  • It only revives apps you actually want running. devkit start marks intent up; devkit stop / stop-all marks it down — so the supervisor never restarts something you deliberately stopped.
  • Crash loops are throttled with exponential backoff (5s → capped at 5min), reset once an app comes back healthy.
  • Each pass also re-checks the proxy, so .localhost routing self-heals even when no devkit command is running.

devkit supervise tick runs a single pass by hand (this is what the launchd agent calls).

Tuning env vars: DEVKIT_SUPERVISE_INTERVAL (seconds between checks, default 10), DEVKIT_SUPERVISE_BACKOFF_BASE (default 5), DEVKIT_SUPERVISE_BACKOFF_CAP (default 300). For a non-Homebrew Caddy setup, set DEVKIT_CADDY_MANAGED=1 so reloads still apply.


Reliability

  • 97 CLI lifecycle tests (including crash recovery, restart policy, and the launchd plist)
  • 18 installer smoke tests
  • GitHub Actions on fresh macOS runners

Explicitly covers stale pid files, orphan recovery, restart pressure, port conflicts, failed starts, out-of-band apps.json edits, malformed registries, and supervised crash recovery.

bash test/test_registry.sh
bash test/test_install.sh

Requirements

devkit bootstrap handles all of these.


State Files

devkit keeps its data in ~/.devkit — a hidden dotfile directory, like ~/.ssh, ~/.aws, or ~/.kube. This is separate from where the binary is installed, so the registry survives reinstalls and Homebrew upgrades and never clutters your home folder.

~/.devkit/apps.json        ← registry (source of truth)
~/.devkit/Caddyfile        ← generated proxy config
~/.devkit/dashboard.html   ← generated dashboard
~/.devkit/logs/<name>.log  ← app logs
~/.devkit/pids/<name>.pid  ← PID files

Override the location with DEVKIT_HOME (e.g. export DEVKIT_HOME="$XDG_DATA_HOME/devkit").

The binary itself lives wherever your install method puts it — /opt/homebrew/bin/devkit (Homebrew), ~/.local/bin/devkit (install script), or bin/devkit in a source checkout. devkit paths prints exactly where everything is.

Upgrading from an older devkit? Earlier versions stored data in ~/devkit. The first time you run any command, devkit moves your registry to ~/.devkit automatically and leaves the old binary/checkout untouched. You can then remove the stale export PATH=".../devkit/bin:$PATH" line from your shell rc if the installer added one.


License

MIT

Ver o original no GitHub

Bom para

Relacionados