# 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

```bash
npm install -g koneck
```

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

## Quick Start

```bash
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`:

```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`:

```json
{ "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