Metadata-Version: 2.4
Name: creativetasks
Version: 2.3.0
Summary: A full-screen terminal chat + coding agent for creativetasks.me
License-Expression: MIT
Project-URL: Homepage, https://creativetasks.me
Keywords: cli,llm,ai,chat,coding-agent,tui,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
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

```bash
pip install creativetasks
ct setup          # paste your ct-live-... key
```

That installs two commands, `ct` and `creativetasks` — the same program under
either name. Zero runtime dependencies: plain stdlib, Python 3.10+.

If `ct` is not found afterwards, pip installed it to a user scripts directory
that is not on your PATH. `pip show -f creativetasks` prints where it went; add that
directory to PATH, or run it as `python -m ct`.

Get an API key at [creativetasks.me](https://creativetasks.me). Config lands in
`~/.ct/config.toml`; environment variables override it:

```bash
export CT_API_KEY="ct-live-..."
export CT_MODEL="opus"
export 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. The CLI already calls `GET /v1/usage` and will show a real
balance the moment that endpoint exists on the gateway.

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

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

## how it works

One loop handles chat and coding: the model always has the tools, so a question
streams back as prose and a task that needs the filesystem calls tools inline.
Everything is stdlib — no dependency tree to audit, no build step, no runtime
surprises.

Source and issues: [creativetasks.me](https://creativetasks.me)
