Metadata-Version: 2.4
Name: creativetasks
Version: 2.5.0
Summary: creativetasks.me unified chat + coding CLI
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

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

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

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

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

| key | does |
|---|---|
| `enter` | send |
| `ctrl+n` | newline (multi-line message) |
| `up` / `down` | input history — or scroll when the box is empty |
| `pgup` / `pgdn` | scroll the transcript |
| `ctrl+u` / `ctrl+w` | kill line / kill word |
| `ctrl+l` | redraw |
| `ctrl+c` | cancel a running turn, or quit when idle |

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

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

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

| flag | short | default | meaning |
|---|---|---|---|
| `--model` | `-m` | `anthropic/claude-opus-5` | model id or alias |
| `--session` | `-s` | — | named session; resumes and autosaves |
| `--workdir` | `-C` | `.` | sandbox root for tools |
| `--max-tokens` | `-n` | 8192 | output ceiling |
| `--reasoning` | `-r` | off | show thinking traces |
| `--no-tools` | | off | chat only, no filesystem |
| `--yolo` | | off | skip confirmations |
| `--max-iters` | | 25 | cap on tool rounds per turn |
| `--file` | `-f` | — | read prompt from a file (repeatable) |
| `--out` | `-o` | — | write the reply to a file |
| `--json` | | — | machine-readable one-shot |

## subcommands

```powershell
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`.
