convez.ai
AgenteDesenvolvimento WebIntermediário

Agent de pair-programming autônomo para desenvolvimento local

Ver no GitHub
BomPluginScore · de 0 a 100

Agent de engenharia de software totalmente autônomo que funciona como aplicação desktop nativa. Lê sua base de código, edita arquivos, executa comandos e entrega código diretamente no seu ambiente local, sem extensões IDE ou servidores em nuvem.

Instalação

$npx convez-ai antojunimaia-ui/Koda

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
32
Forks
11
Acompanhando
0
Saúde
57%
Último commit
há 3 dias
Versão
v26.16.11
Issues abertas
0
Contribuidores
2

Casos de uso

  • Automação de tarefas repetitivas de desenvolvimento
  • Pair-programming contínuo com um agente autônomo
  • Refatoração e edição de código em larga escala
  • Execução de comandos e processos do terminal de forma autônoma
  • Gerenciamento de múltiplos projetos em abas paralelas

Veredito

Koda é um agent maduro (v26.1.5) com arquitetura sólida em Electron + React + TypeScript. Oferece capacidades reais de automação de desenvolvimento local com histórico de sessões, rollback de snapshots e terminal PTY nativo, mas demanda setup local e entendimento técnico para máximo proveito.

README

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

Koda is your ideal development partner.

License Version Electron React TypeScript Discord Support the project

Koda is a fully autonomous software engineering agent that runs as a native desktop application. No IDE extensions, no cloud servers, no clipboard gymnastics — it reads your codebase, edits files, runs commands, and ships code directly in your local environment.

Features • Modes • Workspaces • Tools • Providers • Installation • Build • Architecture


Features

  • Autonomous pair-programming — Koda reads your project structure, understands the architecture, and edits files directly. No copy-paste required.
  • Modern UI by default — opens in the sleek Modern Pro layout with Iconbar on first launch. Classic CLI mode is still available via Settings.
  • Onboarding tour — first-time users get an interactive guided tour highlighting the CWD selector, chat input, mode switcher, workspace split button, and Iconbar. Appears once and is dismissed to localStorage.
  • Chat history — per-project session history stored in localStorage. Hover the Iconbar to open the history panel, load a past session, or delete it. Each conversation is a separate session file — no overwriting.
  • User messages aligned right — in Modern UI, user messages appear as chat bubbles on the right side. Rollback action appears below on hover.
  • Multi-Workspace Split Mode — run multiple independent agent sessions side-by-side in the same window. Each workspace has its own conversation, project context, terminal, and file tracker — with zero cross-talk between instances.
  • Snapshot & rollback — before every message, Koda captures a full in-memory snapshot of all workspace files. Hover any user message and click ↺ to restore both files and agent memory to that exact point.
  • Task queue — send the next task while the agent is still working. Koda queues it and fires it automatically when the current task finishes.
  • Real PTY terminal — native shell integration via node-pty. Koda spawns background processes, waits for output patterns, sends stdin, and kills processes by PID — all autonomously.
  • Interactive terminal panel — a full xterm.js terminal for you to use directly, independent of the agent, with resize support and ANSI rendering.
  • Built-in browser preview — a <webview>-based browser panel with navigation controls, defaulting to localhost:5173.
  • Web navigation agent — via operantid.js, Koda can spawn a sub-agent that controls a real browser to navigate, interact with UI elements, and extract data from websites.
  • Questions tool — the agent can ask up to 10 clarifying questions before acting. Presented one at a time as a wizard panel above the chat input, supporting single and multiple-choice options. Blocks execution until all answers are submitted.
  • Shell approval panel — shell approval requests appear as an inline panel above the chat input. Shows the command with Accept (Once / Base / Full) and Deny buttons.
  • .kodaignore support — create a .kodaignore file in your project root (same syntax as .gitignore) to restrict Koda's access to specific files or folders. Blocked paths are invisible in list_dir, file_find, and search. If the agent tries to read or write a blocked path directly, it receives a clear access-denied message instead of the file content.
  • 4 operation modes — Fast, Planner, Colab, and Teach & Code, selectable from a dropdown in the TitleBar.
  • Skills system — Markdown-based skill files inject specialized instructions into the agent's context on demand. Invoke with /skill-name or let the agent load them autonomously. Global skills in ~/.koda/skills/, project-local in .koda/skills/.
  • Dynamic slash menu — typing / opens a live-filtered dropdown listing all native commands and available skills.
  • Inline diff viewer — file_edit outputs render as a side-by-side visual diff with line numbers.
  • System notifications — native OS notification fires when a long task (>3s) completes and the window is not in focus.
  • Remote Control API — built-in HTTP server (default port 3141) exposes POST /task, GET /status, POST /reset, and GET /messages.
  • MCP support — connect any Model Context Protocol server. Tools are discovered at runtime and injected into the agent's arsenal dynamically.
  • LSP integration — semantic queries via typescript-language-server: hover types, go-to-definition, and symbol resolution.
  • 16 LLM providers — dynamic model listing via API. Switch providers and models from the UI without restarting.
  • File tracker — every file the agent reads or modifies is tracked in-session and surfaced in the context panel.
  • At-mentions (@) — type @ to open a file selector. Koda reads the file and injects it directly into the prompt (capped at 50KB).
  • Drag & drop — drop image files to attach them; drop code files to inject an @[path] mention.
  • Configurable verbosity — toggle output visibility per tool type without affecting agent context.
  • 4 built-in themes — Tokyo Night, GitHub Dark, Cyberpunk Neon, Monokai. Live preview, fully customizable.
  • 32-bit Windows support — separate installers for x64 and ia32 architectures, built independently via GitHub Actions.
  • macOS compatibility — DMG built without code signing requirements. If Gatekeeper blocks the app, run xattr -cr /Applications/Koda.app to remove the quarantine attribute.

Operation Modes

Switchable from the TitleBar via a dropdown selector.

⚡ Fast (default)

Immediate autonomous execution. The agent acts on your request without any planning step.

📋 Spec Development

Before writing any code, Koda enters a read-only exploration cycle and drafts a full specification file (specs.md) at the root of your project. A modal appears for you to Approve or Reject the spec. No files are modified until approval is granted.

👥 Colab

Activates three additional tools: start_collaboration, send_to_advisor, and end_collaboration. Koda can open a multi-turn conversation with a second model instance to brainstorm architecture before implementing.

🎓 Teach & Code

Koda acts as a technical mentor. For every non-obvious change, it explains why that approach was chosen over alternatives. Ideal for learning a codebase.


Multi-Workspace

Koda supports running multiple, fully isolated agent sessions inside a single window.

Activating Split Mode

Click the split panel icon (⊞) in the TitleBar, to the right of the mode selector. A tab bar appears. Each tab represents an independent workspace.

Creating & Managing Workspaces

  • + — creates a new workspace with a fresh agent instance.
  • Click a tab — switches the active workspace instantly.
  • ✕ on a tab — closes that workspace. The last workspace cannot be closed.

Isolation Guarantees

LayerIsolation mechanism
BackendMap<workspaceId, Agent> — each agent has its own LLM conversation, tool state, PTY processes, and MCP connections
IPCAll Electron IPC handlers accept workspaceId as the first argument
TerminalptyStart resolves the working directory from the workspace-specific agent
SessionsloadSession tracks the last-loaded CWD per workspace — switching tabs never reloads another workspace's chat
StreaminguseAgentStream maintains separate chunk buffers and RAF loops per workspace

.kodaignore

Create a .kodaignore file in your project root to restrict what Koda can access. Uses the same syntax as .gitignore:

# Secrets
.env
*.key
secrets/
config/private.json

# Sensitive directories
private/

Behavior per tool:

ToolBehavior when path is blocked
file_readReturns 🚫 Access denied: "path" exists but is restricted by .kodaignore
file_editSame access-denied message, no modification
file_writeSame access-denied message, no file created
list_dirBlocked entries are silently omitted from the listing
file_findBlocked files are filtered out of results
searchResults from blocked files are removed

The agent knows the file exists but cannot see its content — it will not attempt workarounds.


Tool Arsenal

All tools extend BaseTool and are registered in ToolRegistry. The registry enforces mode restrictions and plan-mode write locks before every execution.

ToolDescription
shellSpawns a PTY process via node-pty. Returns PID immediately. Requires user approval for non-read-only commands.
shell_waitPolls a background PTY's output buffer for a regex/string pattern, or waits for process exit.
shell_inputWrites raw stdin to a running PTY process.
kill_ptySends SIGINT or SIGKILL to a background PTY by PID.
list_ptyLists all active background PTY PIDs.
file_readReads file content with optional line range. Respects .kodaignore.
file_writeCreates or overwrites a file. Respects .kodaignore.
file_editReplaces an exact string match within a file. Returns a colored unified diff. Respects .kodaignore.
file_findGlob-pattern file search via globby. Respects .gitignore and .kodaignore.
list_dirLists directory contents with file sizes. Respects .kodaignore.
searchRegex search across files. Uses ripgrep when available. Respects .kodaignore.
lsp_querySemantic queries via typescript-language-server: hover and goToDefinition.
browser_agentSpawns operant-runner.js to control a real browser and return a report.
enter_plan_modeTransitions the agent to read-only plan mode. (Planner mode only)
exit_plan_modePresents the Markdown plan and awaits approval via IPC. (Planner mode only)
start_collaborationInitializes an advisor LLM session. (Colab mode only)
send_to_advisorSends a message to the advisor and streams back the response. (Colab mode only)
end_collaborationTerminates the advisor session. (Colab mode only)
load_skillLoads a skill from ~/.koda/skills/ or .koda/skills/ and injects its instructions into context.
questionsAsks the user up to 10 clarifying questions. Rendered as a wizard panel above the chat input. Blocks execution until all answers are submitted.

Supported Providers

ProviderNotes
OpenRouterHundreds of models via a single key
OpenAIGPT-4o, o1, o3 families
AnthropicAll Claude models
Google GeminiAll Gemini models
GroqAll Groq platform models
DeepSeekAll DeepSeek models
Mistral AIAll Mistral models including Codestral
Together AIAll Together platform models
xAIGrok family
Fireworks AIFireworks models via API
Zhipu AI (Z.AI)GLM family
Maritaca AISabiá family (Brazilian Portuguese optimized)
Koda CloudPremium models via secure proxy — no local keys needed. Displayed as model / Koda Cloud in the UI.
OllamaLocal models via /v1/models or legacy /api/tags
Llama.cppLocal inference via HTTP server on port 8080

Installation

Prerequisites

  • Node.js 20 or higher
  • Git in your PATH
  • An API key from any supported provider (or use Koda Cloud)

Development

git clone https://github.com/antojunimaia-ui/Koda.git
cd Koda
npm install
npm run dev:clean

Use dev:clean to wipe dist-electron/ before starting. Stale build artifacts cause subtle IPC failures.

API keys are stored in localStorage via the settings panel. No .env file is required for the UI.

Environment Variables (optional)

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-...
ANTHROPIC_MODEL=claude-sonnet-4-20250514
MAX_TOKENS=8192
TEMPERATURE=0.3

Native Commands

CommandDescription
/helpShows the command reference
/clear or /resetClears conversation history and agent memory
/tokens or /costDisplays estimated token usage
/model --<name>Switches the active model
/apikey <key>Sets the API key inline
/<skill-name> [message]Activates a skill

Remote Control API

Enable in Settings → Remote Control.

MethodPathAuthDescription
GET/statusPublicAgent status, busy state, current project and model
POST/taskTokenSend a task — body: { "message": "..." }
POST/resetTokenReset conversation remotely
GET/messagesTokenRetrieve full conversation history as JSON
curl -X POST http://100.x.x.x:3141/task \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "run the test suite and fix any failures"}'

Tasks sent via the API appear in chat with a 🌐 Remote badge.


Build & Distribution

# Windows x64 — NSIS installer
npm run dist

# Windows ia32 (32-bit) — separate installer
npm run dist:32

# Linux — AppImage
npm run dist:linux

# macOS — DMG
npm run dist:mac

Output goes to release-build/. GitHub Actions builds x64 and ia32 as completely separate jobs, producing:

  • Koda-Setup-<version>-x64.exe
  • Koda-Setup-<version>-ia32.exe

macOS note: If Gatekeeper shows "app is corrupted", run xattr -cr /Applications/Koda.app in Terminal to remove the quarantine attribute.


Architecture

src/
├── main/                        # Electron Main Process (Node.js)
│   ├── index.ts                 # App bootstrap + all IPC handlers (workspace-aware)
│   ├── core/
│   │   ├── agent.ts             # Agent class: provider lifecycle, message loop, tool orchestration
│   │   ├── conversation.ts      # Message history, microCompact, trimIfNeeded, rollback
│   │   ├── prompt-builder.ts    # Dynamic system prompt assembly (env + project + tools)
│   │   └── context.ts           # Project detection (language, framework, package manager)
│   ├── providers/               # 15 LLM provider implementations (all extend BaseProvider)
│   │   └── base.ts              # BaseProvider, Message, StreamChunk, ToolCall interfaces
│   ├── tools/                   # 19 agent tools (all extend BaseTool)
│   │   ├── index.ts             # ToolRegistry: registration, mode filtering, plan-mode lock
│   │   ├── shell.ts             # ShellTool + PTY registry + KillPty/ListPty/ShellInput/ShellWait
│   │   ├── file-edit.ts         # String-replace edit with unified diff output
│   │   ├── collaborate.ts       # Advisor LLM session (StartColab/SendColab/EndColab)
│   │   ├── plan.ts              # Plan mode state machine + approval Promise
│   │   ├── questions.ts         # Questions tool — wizard panel, blocks via Promise
│   │   └── mcp-tool.ts          # Dynamic MCP tool wrapper
│   ├── services/
│   │   ├── snapshot.ts          # In-memory workspace snapshots (create/restore/list)
│   │   ├── mcp-manager.ts       # MCP server lifecycle + JSON-RPC tool discovery
│   │   ├── lsp-client.ts        # typescript-language-server client
│   │   ├── file-tracker.ts      # In-session file access tracker
│   │   ├── skill-manager.ts     # Loads .md skills from ~/.koda/skills/ and .koda/skills/
│   │   └── webhook-server.ts    # HTTP remote control server
│   ├── config/
│   │   └── settings.ts          # AppSettings, .env loading, provider defaults
│   └── utils/
│       ├── diff.ts              # Unified diff generation + string-replace logic
│       ├── kodaignore.ts        # .kodaignore parser + path filter (minimatch-based)
│       ├── tokens.ts            # Token estimation
│       ├── syntax.ts            # Language detection from file extension
│       └── logger.ts            # Logging utilities
├── preload/
│   └── index.ts                 # contextBridge: exposes window.koda API
└── renderer/                    # React 19 + Tailwind CSS 4
    ├── App.tsx                  # Root orchestrator: multi-workspace state, session routing, IPC wiring
    ├── types/index.ts           # Workspace, AgentInfo, MessageEntry and all shared interfaces
    ├── hooks/
    │   ├── useAgentStream.ts    # IPC event subscriber — per-workspace chunk buffers + RAF flush loops
    │   ├── useSession.ts        # Project session load — workspace-isolated CWD tracking
    │   └── useSessionStorage.ts # localStorage-based session persistence (list/save/delete)
    └── components/
        ├── modern/ModernUI.tsx  # Default UI: sleek backdrop-blur interface with Iconbar
        ├── classic/ClassicUI.tsx# Alternative UI: cyberpunk terminal-inspired interface
        ├── OnboardingTour.tsx   # First-launch guided tour (5 steps, arrow tooltips)
        ├── ChatHistory.tsx      # Per-project session history panel (hover Iconbar to open)
        ├── modals/
        │   ├── PlanApprovalModal.tsx  # Plan approval overlay
        │   ├── QuestionsModal.tsx     # Questions wizard panel
        │   └── ShellApprovalPanel.tsx # Shell approval panel
        ├── messages/
        │   ├── UserMessage.tsx        # Right-aligned bubble in Modern UI, rollback on hover
        │   └── CompactToolView.tsx    # Grouped tool summary view
        ├── WorkspaceTabs.tsx    # Tab bar for switching/creating/closing workspaces
        ├── TitleBar.tsx         # Mode switcher + Workspace Split toggle + window controls
        ├── TerminalPanel.tsx    # xterm.js terminal connected to a live PTY
        ├── BrowserPreview.tsx   # Electron <webview> browser panel
        ├── MCPSettings.tsx      # MCP server configuration UI
        └── BrailleSpinner.tsx   # Animated thinking indicator

Contributing

Read CONTRIBUTING.md before opening PRs. Key points: strict TypeScript (avoid any), focused PRs (one thing per PR), Conventional Commits, and never commit API keys.


License

Distributed under the BSD 3-Clause License.


Ver o original no GitHub

Bom para

Relacionados