Metadata-Version: 2.4
Name: deft-console
Version: 0.12.3
Summary: Deft Console: any coding agent, in your terminal.
Project-URL: Repository, https://github.com/deftai/console
Author: Deft
License: Deft Console
        Copyright (c) 2026 Deft. All rights reserved.
        
        This software is proprietary. No part of it may be copied, modified, distributed or
        used except as permitted in writing by Deft.
        
        Deft Console is built on Toad, Copyright (c) Will McGugan, which Deft uses under a
        commercial license from its author (not under the AGPL).
        
        Third-party packages that Deft Console depends on are distributed under their own
        licenses.
License-File: LICENSE
Classifier: Environment :: Console
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.14
Requires-Dist: aiosqlite==0.22.1
Requires-Dist: bashlex==0.18
Requires-Dist: click==8.4.0
Requires-Dist: format-currency>=0.0.10
Requires-Dist: httpx==0.28.1
Requires-Dist: notify-py==0.3.43
Requires-Dist: packaging==26.2
Requires-Dist: pathspec==1.1.1
Requires-Dist: pillow>=10.3
Requires-Dist: platformdirs==4.9.6
Requires-Dist: psutil==7.2.2
Requires-Dist: pyperclip==1.11.0
Requires-Dist: pywinpty==3.1.2; sys_platform == 'win32'
Requires-Dist: quickjs-ng>=0.18.0.1; sys_platform != 'darwin' or platform_machine != 'x86_64'
Requires-Dist: resvg-py>=0.5.0
Requires-Dist: rich==15.0.0
Requires-Dist: setproctitle==1.3.7
Requires-Dist: textual-diff-view==0.1.5
Requires-Dist: textual-serve>=1.1.2
Requires-Dist: textual-speedups==0.2.1
Requires-Dist: textual[syntax]==8.2.7
Requires-Dist: typeguard==4.5.2
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: watchdog==6.0.0
Requires-Dist: xdg-base-dirs>=6.0.2
Description-Content-Type: text/markdown

# Deft Console

**Any coding agent, in your terminal.**

Deft Console is a terminal app for working with AI coding agents. It speaks the
[Agent Client Protocol](https://agentclientprotocol.com) (ACP), so the same interface works
with Claude Code, Codex, Grok Build, Gemini CLI, Copilot and many more. Run several
sessions at once, with different agents, and keep an eye on all of them from one place.

## What it does

- **Any ACP agent.** Pick an agent from the built-in catalogue (`ctrl+h`), install it from
  there, or run any ACP command with `console acp "<command>"`.
- **Many sessions at once.** Each session has its own agent. Switch with `ctrl+]` and
  `ctrl+[`, or open the **Sessions** dashboard (`ctrl+s`) to see every session, what it's
  doing, and what it's waiting on.
- **Sub-agents you can follow.** When an agent hands work to sub-agents, each gets a live
  card. Open one to see its own conversation, its commands and the messages it exchanges
  with its parent.
- **Rich replies.** Markdown with syntax highlighting, file edits as diffs, and Mermaid
  diagrams drawn right in the conversation, even while they're still streaming in.
- **Live commands.** Commands an agent runs appear as live terminals. Type `!` at the
  prompt to run your own shell commands.
- **Terminals beside the conversation.** `/console:terminal` opens a shell in a pane. Split,
  drag and zoom panes, with the keyboard (`ctrl+\`) or the mouse. A project's layout comes
  back the next time you open it, with a fresh shell in each terminal. Agents can open a
  terminal too, after asking you, and can only touch the ones they opened.
- **The agent asks, you answer.** Permission requests, plans, forms and multiple-choice
  questions appear inline, with keyboard shortcuts.
- **Session options and history.** Change the model and reasoning level (`f3`), and list,
  reopen or delete an agent's earlier sessions (`/console:sessions`).
- **Usage at a glance.** Tokens, context used and cost, per session and in total, in the
  Sessions dashboard (`ctrl+s`).
- **Works with your terminal.** Console reports each session's status to terminals that
  support the OSC 7501 program-status protocol.

## Install

### For humans

You need access to the private `deftai/console` repo (an SSH key on GitHub) and
[uv](https://docs.astral.sh/uv/).

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh        # if you don't have uv
uv tool install --python 3.14 git+ssh://git@github.com/deftai/console.git
console
```

On Windows, you also need [Git](https://git-scm.com/downloads/win) (one of Console's
dependencies is installed from GitHub). In PowerShell:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # if you don't have uv: then open a new window
uv tool install --python 3.14 git+ssh://git@github.com/deftai/console.git
console
```

If `console` isn't found, run `uv tool update-shell` and open a new window. Use Windows Terminal, which can show images and pages in Console. Console has been tried on
Windows 11; pasting images from the clipboard isn't there yet.

uv installs Python 3.14 for Console if you don't have it. To update, run
`uv tool upgrade deft-console`; to remove it, `uv tool uninstall deft-console`.

You can also install a release's wheel, downloaded with the [GitHub CLI](https://cli.github.com):

```bash
gh release download --repo deftai/console --pattern '*.whl'
uv tool install --python 3.14 ./deft_console-*.whl    # on Windows, give the wheel's full name
```

### For agents

If you're an AI agent asked to install Deft Console for a user, follow these steps in
order. Each is non-interactive; stop and tell the user if one fails.

1. **Check for uv:** `command -v uv`. If it's missing, install it with
   `curl -LsSf https://astral.sh/uv/install.sh | sh`, then make it available in the
   current shell (`source "$HOME/.local/bin/env"`, or use `$HOME/.local/bin/uv`). On Windows,
   check with `Get-Command uv` and `Get-Command git`, and install uv with
   `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`, then
   use `$HOME\.local\bin\uv.exe`, as the current shell's PATH doesn't have it yet. If Git is
   missing, tell the user: it's needed for the next steps.
2. **Check repo access:** `git ls-remote git@github.com:deftai/console.git HEAD`. If this
   fails, the user's GitHub account or SSH key has no access: stop and tell them. Don't
   create keys or change their GitHub settings.
3. **Install:** `uv tool install --python 3.14 git+ssh://git@github.com/deftai/console.git`
   (uv fetches Python 3.14 if needed). To update an existing install, use
   `uv tool upgrade deft-console` instead.
4. **Verify:** `console --version` prints the version. If `console` isn't found, run
   `uv tool update-shell` and tell the user to open a new terminal.
5. **Optional agent tools:** `node --version` should be 20 or later for Claude, Codex and
   SABAL. If there's no Node.js, Console offers to download its own copy when an agent needs
   it, so report what's missing rather than installing system software unasked.
6. **Hand over:** Console is a full-screen terminal app, so let the user start it
   themselves: `console` for the agent picker, or `console -a demo` and type `tutorial`.
   Don't sign in to agents (Claude, Codex, Grok) on the user's behalf.

## Getting started

```bash
console                    # the agent picker, in the current directory
console ~/code/my-project  # ... in another project
console -a demo            # the built-in Console Demo
console -a claude          # straight into an agent: claude, codex, grok, sabal, …
```

New to Console? Run `console -a demo` and type `tutorial`: twelve short lessons walk
through every part of the app, and you can try each one as you go. Type `menu` there for
every demo.

### Recommended agents

| Agent | What it is | Needs |
|---|---|---|
| **Console Demo** | A built-in, scripted agent with a tutorial and a demo of every feature | Nothing |
| **SABAL** | A fun VVSLM (Very Very Small Language Model): classic text adventures | [Node.js](https://nodejs.org) 20+ |
| **Grok Build** | xAI's coding agent | The [Grok CLI](https://x.ai/cli) |
| **Codex** | OpenAI's coding agent | Node.js 20+; a ChatGPT sign-in or an OpenAI API key |
| **Claude Code** | Anthropic's coding agent | Node.js 20+ and [Claude Code](https://claude.com/claude-code), signed in |

Many more agents are in the picker (`ctrl+h`); choose one and pick **Install** to set it
up. Agents that need signing in ask when they start, and Console offers each agent's own
sign-in methods: a browser login, a terminal login or an API key.

### Your own agents

Put an agent file (`*.toml`) in the `agents` folder next to your settings, usually
`~/.config/toad/agents/` (`console settings` shows where your settings live). It appears in the picker and
works with `console -a`. Only four fields are needed:

```toml
identity = "my-agent.example"
name = "My Agent"
short_name = "mine"            # console -a mine
run_command."*" = "my-agent --acp"
```

Any other field of the built-in agents (`description`, `help`, `welcome`, `actions`, ...)
works too. A file with the identity of a built-in agent replaces it. A file that can't be
read is skipped, and the reason is logged.

### Keys

| Key | Does |
|---|---|
| `ctrl+h` | The agent picker: start a session with any agent |
| `ctrl+s` | The Sessions dashboard (`n` new session, `enter` opens a row) |
| `ctrl+]` / `ctrl+[` | Next / previous session |
| `f3` (or `ctrl+g`) | Session options: model, reasoning level and more |
| `alt+↑` / `alt+↓` (Option on macOS) | Move between blocks in the conversation; `enter` opens a block's menu, where `b` opens an image or diagram in a pane beside it |
| `ctrl+\`, then a key | Panes: arrows or `hjkl` move focus, with `shift` to swap; `v` and `s` open a terminal right and below; `z` zooms; `x` closes; `<` `>` `+` `-` resize. Pressed twice, it goes to the terminal |
| `escape` | Cancel the agent's turn, or close a dialog |
| `f1` | Help for what's focused |
| `f2` | Settings |
| `ctrl+p` | The command palette: themes, modes and keys |

At the prompt, `/` lists commands (Console's own start with `/console:`), `@` mentions a
file, and `!` runs a shell command.

## Command line

| Command | Does |
|---|---|
| `console [PATH]` | Start in `PATH` (default: the current directory) |
| `console -a AGENT [PATH]` | Start a session with an agent from the catalogue, by short name |
| `console -a AGENT --resume SESSION_ID [PATH]` | Reopen one of that agent's sessions instead of starting a new one. For Claude Code, the ID is a Claude session ID (the name of its `.jsonl` under `~/.claude/projects/`): `console -a claude-deft --resume 8f07f701-…`. `console acp` takes `--resume` too |
| `console acp "COMMAND" [PATH]` | Run any ACP agent from its command, e.g. `console acp "npx -y some-acp-agent"` |
| `console serve` | Serve Console as a web app (this machine only, unless `--host` says otherwise) |
| `console serve --tailscale` | Serve it to your own devices over Tailscale: listens on this machine's Tailscale address only, and lets in only your tailnet login |
| `console serve --tailscale-https` | The same over HTTPS, through `tailscale serve` (Tailscale's certificate) |
| `console settings` | Show where settings live |
| `console about` | Version and environment details |
| `console --version` | The version |

### Serving over Tailscale

Console's web serving has no sign-in of its own: anyone who can reach the port can use it, and it runs commands. So by default it serves this machine only, and serving anywhere else (`--host 0.0.0.0`) prints a warning. To use Console from your phone or another computer, serve it on [Tailscale](https://tailscale.com):

- `--tailscale` listens on this machine's Tailscale address, and prints its MagicDNS link (`http://mac.tail1234.ts.net:8000`). Each connection is checked with `tailscale whois`.
- `--tailscale-https` listens on 127.0.0.1 only, with `tailscale serve` in front for HTTPS (`https://mac.tail1234.ts.net:8000`). Tailscale says who is connecting in a header. It adds its own port to `tailscale serve`, leaves the others alone, and removes its port when Console stops.

Either way, only allowed logins get in: by default the login that owns this machine. `serve.tailscale-users` in settings (or `CONSOLE_TAILSCALE_USERS`) lists others, comma or space separated, and `*` lets in anyone on the tailnet. Console won't start if Tailscale isn't connected, rather than serving somewhere else.

The flags work on `console --serve` and `console acp --serve` too. To make Tailscale the default, set `serve.tailscale` to `bind` or `https`, or `CONSOLE_TAILSCALE=bind|https`. `--no-tailscale` turns it off for one run. The flag wins over the environment, and the environment over the setting.

### Driving panes from a script

Anything running in a Console terminal pane or the `!` shell can drive that session's panes with
`console pane`. From another terminal, it finds the session for the current folder, or the only
one running (`console pane sessions` lists them, for `--socket`):

```sh
new=$(console pane split --current --direction down)
console pane send "$new" "npm test" --enter
# ...once the tests have run:
console pane read "$new" --lines 20
console pane close "$new"
```

`console pane show FILE` opens an image, or a Mermaid diagram (`.mmd`), in a pane of its own.
It also has `list`, `move`, `focus`, `call`, `action` for anything else, `events` to follow
what happens as lines of JSON, and `schema` to list every action and event. It prints JSON when
piped. Underneath is JSON-RPC, one object per line, on the socket in `$CONSOLE_PANE_SOCKET`.

## Development

```bash
git clone git@github.com:deftai/console.git && cd console
uv run console           # run from the checkout
uv run pytest            # the tests, in parallel (add -n0 to run them one at a time)
```

To release, set `version` in `pyproject.toml`, then push a matching tag:
`git tag v0.7.0 && git push origin v0.7.0`. The release workflow runs the tests, builds the
package and creates a GitHub release with the wheel attached.

## License

Deft Console is proprietary software. See [LICENSE](./LICENSE).
