AI beside your terminal,
not above it.
When the terminal raises a question, type #? and ask in place.
Koshell is in development, building in public. Leave your email to be notified at launch.
No spam — launch announcement only.
How it works
Wrap your shell
# wrap this terminal once $ koshell # or auto-wrap every terminal — first line of ~/.zshrc eval "$(koshell shell-init zsh)"Both are transparent: when the AI is away, it is just your shell. Same prompt, same config, same exit codes.
Something happens
✘ port is already allocatedA command fails. Output doesn't make sense. A REPL gets stuck. The question is right there on your screen.
Ask in place
$ #? why did this failType
#?and ask. The answer streams into the terminal, grounded in the screen you are already looking at — no selecting output, no pasting it into a chat window, no explaining where it came from.
Not a chatbot. Not an agent.
The same failure, twice.
✘ port is already allocated
pasted this from my terminal — it happened after docker compose up, in the project I mentioned earlier. Any idea why?
Could you also paste your compose file and what's on port 5432?
$ docker compose up
✘ port is already allocated
$ #? why did this fail
Another process already owns port 5432 — most likely the
Postgres you started yesterday. `docker ps` will show it.
$ ▋Not a replacement terminal
Koshell wraps your existing shell and setup. Your prompt, your aliases, your muscle memory — all untouched.
Not a separate chat room
There is nothing to copy and nowhere to paste it. The context is the terminal you are already in.
Not an agent that owns the execution loop
Koshell observes and explains. You keep every keystroke; it never runs a command for you.
Principles
observe-only
You stay the operator
The AI explains, diagnoses, and suggests. It never executes anything. While an answer streams in, the terminal stays yours — keep typing, or hit
design-0006 · Ctrl+C semantics (opens in a new tab)Ctrl+Cto cut the answer off.fail-open
It can never lock you out
Koshell fails open. If the AI side is down, you have a plain, transparent shell wrapper. If startup fails, it hands over to your real shell. Exit codes pass through faithfully, and one variable (
fix-0006 · exit-code fidelity & fail-open (opens in a new tab)KOSHELL_NO_AUTO=1) turns it off entirely.bring-your-own-key
Local-first, your keys
Bring your own key — OpenAI, Anthropic, OpenRouter, or a custom provider. No account, no cloud, no telemetry. Nothing leaves your machine except the calls to the provider you configured, and the local event log is structurally incapable of carrying screen content — and is never uploaded.
design-0007 · what the event log can't contain (opens in a new tab)
Pulled from the public design & fix docs in the repo.
Free and open source
The terminal and the #? loop are open source and free forever. There is no paid edition today; if one ever exists, it will add optional depth on top — the core loop will never move behind a paywall.Apache-2.0 licensed. Runs on macOS and Linux, bash & zsh today.
From the blog
- I instrumented my own product and the data killed my favorite feature
Three weeks of dogfooding telemetry falsified Koshell's core interaction. Here is the event log design, the trace analysis, and the decision that came out of it.