KONECK

Kinetically Orchestrated Neural Execution Engine for Code

A CLI AI coding agent that works like Claude Code or Codex CLI — drop into a chat, give it a task, and it reads, writes, and runs code autonomously using any LLM provider.

Install

npm install -g koneck

Then run koneck — the first-run wizard sets up your API key and provider.

Quick Start

koneck                              # interactive chat (first run → setup wizard)
koneck "add validation to auth.ts"  # one-shot task
koneck --pr "fix the flaky tests"   # task + open a PR when done (from a clean feature branch)

Providers

| Provider | Env Var | Default Model | |---|---|---| | omni (OmniRoute) | OMNI_ROUTE_API_KEY | auto/best-coding | | openai | OPENAI_API_KEY | gpt-4o | | anthropic | ANTHROPIC_API_KEY | claude-opus-4-5 | | google | GOOGLE_API_KEY | gemini-2.0-flash | | groq | GROQ_API_KEY | llama-3.3-70b-versatile | | deepseek | DEEPSEEK_API_KEY | deepseek-coder | | mistral | MISTRAL_API_KEY | mistral-large-latest | | together | TOGETHER_API_KEY | meta-llama/Llama-3-70b-chat-hf | | xai | XAI_API_KEY | grok-beta | | perplexity | PERPLEXITY_API_KEY | llama-3.1-sonar-large-128k-online | | moonshot | MOONSHOT_API_KEY | moonshot-v1-8k | | cohere | COHERE_API_KEY | command-r-plus | | ollama (local) | (none) | llama3.2 |

CLI Reference

Flags

| Flag | Description | |---|---| | -p, --provider | LLM provider to use (e.g. openai, anthropic, omni) | | --base-url | Override the provider base URL | | -m, --model | Model name to use | | -t, --max-turns | Maximum agentic turns before stopping | | -a, --approve | Auto-approve all tool calls | | -w, --worktree | Run in an isolated git worktree | | -C, --cwd | Set working directory | | -v, --verbose | Print full tool call input/output | | --ci | Non-interactive CI mode | | --json | Output structured JSON | | --budget | Token/cost budget limit | | --pr | Open a pull request after a completed, preflight-verified task. Requires gh, a clean non-default branch, and committed task changes. | | -V, --version | Print version | | -h, --help | Show help |

Subcommands

| Subcommand | Description | |---|---| | chat | Start an interactive chat session (default) | | doctor | Check provider connectivity and configuration | | stats | Show usage statistics | | watch [pattern] | Watch files matching pattern and re-run on changes | | setup | Interactive first-run configuration wizard | | auth [status\|login\|logout] | Inspect, store, or clear Koneck-managed authentication. Logout keeps provider/model preferences and never changes environment variables. | | init | Generate a KONECK.md for the current project | | completion [shell] | Print shell completion script (bash/zsh/fish) | | refactor rename <old> <new> | Rename a TypeScript symbol across the project using its AST. | | refactor extract <file> <Class> | Extract a class’s public interface without overwriting an existing interface file. | | refactor move <symbol> <from> <to> | Move a TypeScript declaration and update import sites. | | refactor split <file> | Ask the active model to split a large file while preserving compatibility exports. | | --sessions | List recent sessions | | --resume <id> | Resume a previous session by ID |

Quality and governance

KONECK verifies changed projects after a coding task by running the detected lint and test commands. In chat, run /quality at any time to repeat that check.

Interactive workflow

The interactive chat has a searchable command palette: type / on an empty line, then filter, navigate with the arrows, and press Enter. The most useful controls for an intentional coding loop are:

| Command | What it gives you | |---|---| | /goal <outcome> | Keeps a session objective present across turns, resumes, and forks. | | /changes, /diff | See staged, unstaged, and untracked work before asking for another change. /diff renders a bounded patch for new text files too. | | /preflight | Runs detected quality gates and checks the actual resulting patch, including untracked files. | | /ship | Runs the readiness gate and, only when it passes, begins an enforced read-only review of the workspace. It never commits for you. | | /review or /security-review | Get evidence-backed, read-only review of the complete workspace diff. | | /checkpoint [name|list] | Save a named Git restore point for tracked and non-ignored workspace files, including binary files; list inspects saved points. | | /revert list | Inspect automatic edit checkpoints and named restore points. Use /revert <id> --preview to see the exact affected paths; named workspace restores require /revert <id> --confirm and create an exact undo snapshot first. | | /send <repo> <task> / /ask <repo> <question> | Hand work or a question to another running KONECK session. | | /context, /doctor, /mcp | Inspect the live model window, provider health, and available integrations. |

/permissions on keeps approval prompts for writes and commands; /permissions off removes that session-level friction, except where workspace policy still requires approval.

--worktree (or /worktree on) isolates a task only when the opened workspace owns its Git repository. KONECK will not create branches or worktrees in a repository that merely encloses the folder you opened.

Use /logout in chat (or koneck auth logout) to remove only the API key Koneck stored itself. It preserves your provider/model preferences and never edits shell environment variables or vaults.

Native refactor commands operate on TypeScript ASTs and are best paired with /checkpoint or a Git commit before broad changes, followed by /preflight.

Every top-level tool operation is also appended to .koneck/audit/ as a structured JSONL event with its timestamp, duration, outcome, and a redacted action summary. File contents are never stored in the audit trail. Use /audit or /audit 50 in chat to inspect recent activity.

Repository policy

Run /policy init in chat to create .koneck/policy.json. The policy is enforced before built-in file and command tools execute. It can protect secret paths, block dangerous command patterns, require approval for selected tools, and limit writes to specified paths.

Workspace trust and updates

When KONECK is opened in an interactive folder, it asks whether it may access that workspace for the current session, always, or not at all. Persistent workspace approvals are stored locally in the user's KONECK configuration.

KONECK also checks the npm registry at most once per day and shows an upgrade notice when a newer published version is available. It never installs or publishes updates automatically.

KONECK.md

Place a KONECK.md in your project root to give KONECK project-specific context — architecture notes, conventions, commands to run before editing, files to avoid, and anything else the agent should know up front.

Run koneck init to auto-generate one from your existing codebase, or koneck setup to walk through it interactively.

MCP Servers

KONECK supports Model Context Protocol servers declared in .koneck/mcp.json:

// .koneck/mcp.json
{
  "servers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
  }
}

Servers are started automatically when KONECK launches and their tools become available to the agent.

Configuration

Global config lives in ~/.koneckrc:

{ "provider": "anthropic", "model": "claude-opus-4-5", "baseURL": "https://..." }

Project-level config can be placed in .koneck/config.json and takes precedence over the global config.

License

MIT