Quickstart

Zero-to-first-prompt in about five minutes. Assumes a ScaiGrid endpoint and either a ScaiKey account or a ScaiGrid sgk_live_... API key.

1. Install#

Pick one. Both end up with a scaiflux command on your $PATH.

Option A — standalone binary (no Python needed)#

The simplest option for end users. One file, no dependencies.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Replace VERSION with the release you want.
VERSION=0.1.0
BASE=https://downloads.scailabs.ai/dist/scaiflux
NAME=scaiflux-${VERSION}-linux-x86_64

curl -fLO "$BASE/$NAME.gz" \
  && curl -fLO "$BASE/$NAME.gz.sha256" \
  && sha256sum -c "$NAME.gz.sha256" \
  && gunzip "$NAME.gz" \
  && chmod +x "$NAME" \
  && mkdir -p ~/.local/bin \
  && mv "$NAME" ~/.local/bin/scaiflux

Make sure ~/.local/bin is on $PATH (most shells already do this; if not, add export PATH="$HOME/.local/bin:$PATH" to your rc file). Linux x86_64 only at v0.1.0 — see Install for full details and troubleshooting.

Option B — Python install (devs / contributors)#

Use this if you want to hack on ScaiFlux itself, or if you need the MCP client or plugin entry-point discovery (neither is in the binary).

1
2
3
4
5

git clone <this repo>           # adjust to your remote
cd scaiflux
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,mcp]"     # dev extras + MCP client support

Or via pipx for the wheel without cloning:

1

pipx install scaiflux

2. Setup#

Recommended — run the wizard:

1

scaiflux setup

Three prompts: pick an endpoint (defaults to ScaiLabs ScaiGrid at https://scaigrid.scailabs.ai), paste a ScaiGrid API key (sgk_live_...), pick a default model from the discovered catalog, and optionally scaffold .scaiflux.json + SCAIFLUX.md in the current directory. The session is cached in ~/.scaiflux/credentials.json (mode 0600). scaiflux logout wipes it.

Already have an OAuth-capable ScaiKey account and prefer the browser flow? Skip the wizard and run scaiflux login directly:

1
2
3
4
5

export SCAIGRID_BASE_URL="https://scaigrid.example.com"
export SCAIKEY_BASE_URL="https://scaikey.example.com"
export SCAIKEY_TENANT="your-tenant-slug"
export SCAIKEY_CLIENT_ID="scaiflux-cli"     # pre-registered public client
scaiflux login

Or fully headless with an API key (no wizard prompts):

1
2
3

scaiflux login --scaigrid-url https://scaigrid.scailabs.ai \
               --api-key sgk_live_xxxxxxxx \
               --default-model scailabs/poolnoodle-omni

3. Verify#

1

scaiflux doctor

Expect a report along these lines:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

ScaiFlux doctor — 12/13 checks passed
  ✓ python_version: 3.13.5
  ✓ scaiflux_version: 0.1.0
  ✓ platform: Linux-6.12-x86_64
  ✓ inference_credentials: base_url=https://scaigrid.example.com/oai/v1
  ✓ scaikey_session: stored at /home/you/.scaiflux/credentials.json
  ✓ bash_available: bash is on PATH
  ✓ workspace_writable: /home/you/projects/scaiflux
  · config_loaded: no config files
  ✓ git_available: git on PATH (for /diff, /commit, /release-notes)
  ✓ gh_available: gh on PATH (for /pr, /issue)
  ✓ sandbox_available: unshare, firejail
  ✓ terminal: tty=True term=xterm-256color
  ✓ mcp_servers: (none configured)
  ✓ plugins: (none discovered)

Counts vary by host — git_available and sandbox_available flip to warnings if the binary isn't installed. mcp_servers and plugins report the configured surface; both are empty until you add servers / plugins.

4. First prompt#

1

scaiflux prompt "what's 2 + 2?"

You'll see the response stream to stdout.

5. Scaffold a workspace#

1
2

cd ~/projects/experiment     # or any directory
scaiflux init

Creates:

• .scaiflux.json — starter config (model, permissions.mode, hooks).
• SCAIFLUX.md — project memory file, loaded into every system prompt.
• .gitignore — appends .scaiflux/sessions/ and .scaiflux/settings.local.json.

Open .scaiflux.json to see the defaults; open SCAIFLUX.md to write project-specific guidance for the assistant.

6. First tool invocation#

Default permission mode from scaiflux init is workspace-write. Try:

1
2

scaiflux prompt "create hello.txt with the text 'hi from scaiflux'"
cat hello.txt

The assistant invokes write_file inline; you'll see a tool_use block roundtrip, then the synthesis.

7. REPL#

1

scaiflux repl

Inside:

1
2
3
4
5

scaiflux> /help             # list all slash commands
scaiflux> /files **/*.py    # glob from the slash command surface
scaiflux> /cost             # cumulative tokens + estimated $ for the session
scaiflux> count the lines in README.md
scaiflux> /exit

Tab completion covers slash commands, the models discovered at login, permission modes, and recent session IDs.

8. Permission modes#

Lock the assistant down:

1
2

scaiflux prompt --permission-mode read-only "delete hello.txt"
# → the write_file attempt returns an is_error result

Interactive approval per call:

1
2

scaiflux prompt --permission-mode prompt "run 'ls'"
# → prompt on stderr: Approve tool call 'bash'? [y/N]:

Unattended danger mode (skips all prompts):

1

scaiflux prompt --dangerously-skip-permissions "..."

9. JSON output#

For scripts / pipelines:

1

scaiflux prompt --output-format json "summarize README.md" | jq .message

The JSON envelope includes message, model, iterations, stop_reason, tool_uses, tool_results, usage, estimated_cost, and auto_compaction (non-null when the token window filled).

10. Resume / replay / fork a session#

Every run persists to .scaiflux/sessions/<id>.jsonl. Resume the most recent:

1

scaiflux prompt --resume latest "continue where we left off"

Or by id: --resume session_1745....

Inspect or branch a stored session without resuming it:

1
2
3

scaiflux session list
scaiflux session replay <id|latest>            # print the transcript
scaiflux session fork <id|latest> --at 3       # branch a new session at turn 3

Inside the REPL, the same actions live under /session {list,resolve,replay,fork}.

10b. Edit project memory#

1
2
3
4

scaiflux repl
scaiflux> /memory               # list memory files loaded into the prompt
scaiflux> /memory edit          # opens SCAIFLUX.md in $EDITOR
scaiflux> /memory edit SCAIFLUX.local.md

Three memory files are recognized: SCAIFLUX.md, SCAIFLUX.local.md, .scaiflux/instructions.md. They're loaded into the system prompt in that order on every turn.

10c. Workflow run mode#

Each workflow that has a clear action accepts a run argument that executes the generated artifact (opt-in, never automatic):

1
2
3
4
5

scaiflux> /commit                   # render a conventional commit message
scaiflux> /commit run               # also pipe it into `git commit -F -`
scaiflux> /pr                       # render a PR title + body
scaiflux> /pr run                   # also call `gh pr create`
scaiflux> /issue run fix the readme # call `gh issue create` with this subject

Without run, the workflows are read-only.

11. Add a plugin (optional)#

Plugins are directories with a plugin.json manifest. Minimal example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

mkdir -p external-plugins/hello/tools
cat > external-plugins/hello/plugin.json <<'JSON'
{
  "name": "hello",
  "version": "1.0.0",
  "tools": [
    {
      "name": "hello_echo",
      "description": "Echo JSON input verbatim",
      "inputSchema": {"type": "object"},
      "command": "./tools/echo.sh",
      "requiredPermission": "read-only"
    }
  ]
}
JSON

cat > external-plugins/hello/tools/echo.sh <<'SH'
#!/usr/bin/env bash
cat
SH
chmod +x external-plugins/hello/tools/echo.sh

Register it in .scaiflux.json:

{
  "plugins": {"externalDirectories": ["./external-plugins"]},
  "enabledPlugins": {"hello@external": true}
}

Verify:

1
2

scaiflux plugin list
# → hello@external  v1.0.0  (external, enabled, tools=1)  — .../external-plugins/hello

The hello_echo tool is now in the registry and the model can invoke it like any built-in tool.

12. Configure an MCP server (optional)#

If you installed with [mcp], add a server to .scaiflux.json:

{
  "mcp": {
    "servers": {
      "search": {"command": "uvx", "args": ["mcp-search"]}
    }
  }
}

Verify startup:

1
2

scaiflux mcp status
# → search  [connected]  tools=3

Its tools appear as search__<tool> in the registry.

Where to go next#

• USAGE.md — full subcommand + flag table + slash command inventory.
• PARITY.md — parity harness overview; run pytest tests/parity -q.
• CLAUDE.md — architecture map for contributors.
• ROADMAP.md — post-v0.1.0 backlog.

Troubleshooting#