ct — creativetasks.me CLI

One command, one interface. ct opens a full-screen chatbox in your terminal: you type a message, the model answers, and when the task needs the filesystem it calls tools inline — reading, editing and running commands in front of you, asking before it changes anything.

Zero runtime dependencies. Plain stdlib, Python 3.10+.

install

cd d:\creativetasks\cli
pip install --user .
ct setup          # paste your ct-live-... key

That installs two native launchers, ct.exe and creativetasks.exe, into your user scripts directory:

C:\Users\<you>\AppData\Roaming\Python\Python312\Scripts

Make sure that directory is on your PATH, then ct runs from anywhere — no wrapper script, no python -m:

ct                # full-screen interface
creativetasks     # same thing, longer name

A plain pip install . (without --user) writes to the system Python Scripts\ directory instead, which needs an elevated shell.

Config lands in ~/.ct/config.toml. Environment variables override it:

$env:CT_API_KEY  = "ct-live-..."
$env:CT_MODEL    = "opus"
$env:CT_BASE_URL = "https://api.creativetasks.me/v1"

use

Run ct with no arguments for the full-screen interface:

┌────────────────────────────────────────────────────────────────┐
│ ct · claude-opus-5              session:bugfix  D:\creativetasks│
│ › fix the streaming bug in the SSE reader                      │
│                                                                │
│ ● read_file cli/ct/core.py                                     │
│   ✓ 280 lines                                                  │
│ ● edit_file cli/ct/core.py                                     │
│   ✓ edited (1 replacement)                                     │
│                                                                │
│ Swapped the blocking read(512) for line-wise iteration.        │
│────────────────────────────────────────────────────────────────│
│ › now run the tests                                            │
│  ready        ttft 2310ms · 4,182 tok   enter send · /help     │
└────────────────────────────────────────────────────────────────┘

Anything else is headless — it streams to stdout and exits, so pipes and scripts work the way you would expect:

ct "write a bash one-liner that counts .py files"
ct -m sonnet "quick take on X"
Get-Content prompt.txt | ct
ct --json "summarise this repo" > out.json
ct -f notes.md -o summary.md

keys

tool permissions

Reads run silently. Anything that writes to disk or runs a shell command stops and asks first:

 write_file  src/main.py
 + def main():
 +     print("hello")
 [y] allow   [n] skip   [a] always   [q] abort turn

a allows that tool for the rest of the session. --yolo skips every prompt. --no-tools turns the filesystem off entirely and gives you plain chat.

In headless mode there is nobody to ask, so guarded tools are refused unless you pass --yolo.

Every path is pinned under the working directory (-C, default .), so a tool call cannot reach outside it. Shell commands inherit that directory and a 60s timeout.

slash commands

Type / and the full menu appears above the input, filtering as you keep typing. Arrow keys move, Tab completes, Esc dismisses, Enter runs.

• /help — show this list
• /model <name> — swap model for the rest of the session
• /models — list every model the gateway offers
• /api [key] — show or replace the API key
• /usage — tokens, timing and estimated cost
• /mcp [list|reload] — MCP servers and their tools
• /tools [on|off] — toggle filesystem tool access
• /yolo [on|off] — skip tool confirmation prompts
• /reasoning [on|off] — show or hide thinking traces
• /clear — drop the conversation history
• /retry — re-run the last user message
• /session <name> — switch to a named session
• /sessions — list saved sessions
• /save <path> — write the transcript to a file
• /quit — exit ct

MCP servers

ct speaks the Model Context Protocol over stdio. Declare servers in ~/.ct/mcp.json using the same shape Claude Desktop uses, so an existing config pastes straight in:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:\code"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

/mcp init writes a starter file, /mcp shows what is connected, /mcp reload reconnects after an edit. Servers start in the background, so a slow or broken one never delays startup — it just reports as failed.

Their tools are namespaced server__tool and offered to the model alongside the built-ins. MCP tools are not covered by the built-in sandbox — a server can do whatever it was written to do — so only add servers you trust.

usage and cost

/usage reports what this session and every past session spent:

this session
  tokens            2,481 in / 1,102 out
  turns             3
  model time        54.7s  (avg 18.2s, slowest 38.2s)
  throughput        20 tok/s
  est. cost         $0.13

all time
  requests          148
  tokens            184,220 in / 61,405 out
  est. cost         $2.41

The status bar counts up live while the model works (⠹ thinking 4.2s) and reports ttft, duration and tok/s when the turn lands.

Dollar figures are local estimates, computed from a price table in ct/usage.py — the gateway does not report per-request cost to an API key, and your real balance lives behind the web dashboard's 2FA. To get a real balance in /usage, add the endpoint in docs/worker-usage-endpoint.md; the CLI already calls it and will use it the moment it exists.

Raw per-call records are appended to ~/.ct/usage.jsonl.

shipping a binary

python build.py          # dist/ct.exe, one file, ~8.6 MB
python build.py --dir    # dist/ct/, starts faster, ship as a zip

The result runs on a machine with no Python installed — drop it anywhere on PATH. The one-file build unpacks to a temp directory on each launch, which costs about a second of startup; --dir avoids that.

flags

subcommands

ct models                  # list available models
ct sessions ls             # saved sessions
ct sessions show <name>    # replay a transcript
ct sessions rm <name>      # delete one
ct setup                   # write the config file

layout

ct/
  core.py     config, sessions, SSE client, delta folding
  term.py     ANSI, Windows VT setup, raw key input, wrapping
  commands.py the slash-command registry (palette + /help + dispatch)
  tools.py    built-in tool surface, sandbox, permission classes
  mcp.py      MCP stdio client: handshake, tool discovery, dispatch
  usage.py    token/cost accounting, ~/.ct/usage.jsonl
  ui.py       screen regions, transcript blocks, composer, palette
  app.py      the unified turn loop
  __main__.py argument parsing, headless mode
build.py      standalone binary via PyInstaller
tests/        84 tests, no network required
docs/         worker patch for a real credit balance

Run the tests with python -m unittest discover -s tests.