Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,11 @@ ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Disable the network fetch entirely (use only the bundled snapshot):
# PARALLAX_DISABLE_MODELS_FETCH=1

# --- Updates ---
# On startup Parallax checks npm for a newer version and shows the upgrade
# command (it never installs anything itself). Disable the check:
# PARALLAX_NO_UPDATE_CHECK=1

# --- Interface ---
# On a TTY, `parallax` opens the interactive TUI. Force the plain line-based
# renderer instead (e.g. for logging):
Expand Down
19 changes: 11 additions & 8 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -158,17 +158,20 @@ jobs:

- name: Publish to npm with provenance
if: ${{ steps.release.outputs.needs_publish == 'true' }}
env:
PACKAGE_VERSION: ${{ steps.release.outputs.package_version }}
run: |
set -euo pipefail

if [[ "${PACKAGE_VERSION}" == *-* ]]; then
npm_tag=next
else
npm_tag=latest
fi
npm publish --provenance --tag "${npm_tag}" --access public
# Pre-1.0 policy: the newest build IS the release, so publish it under
# `latest` even when it is a prerelease (0.1.0-beta.N). This is what makes
# a plain `npm install --global @singularitycolabs/parallax` fetch the
# newest version — the default install resolves the `latest` dist-tag.
#
# We deliberately set a single tag here: trusted publishing (OIDC)
# authorizes only `npm publish`, not a follow-up `npm dist-tag add`, so we
# can't also move `next` in the same run. That's fine pre-1.0 — the app's
# update notice points at the plain (latest) install command. When a
# stable 1.0.0 line begins, reintroduce a `next` channel for prereleases.
npm publish --provenance --access public --tag latest

- name: Create GitHub Release
env:
Expand Down
72 changes: 49 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,25 +21,29 @@ proposes actions; deterministic code validates, authorizes, and executes them.

## Install

Install the beta CLI globally:
Install the CLI globally:

```bash
npm install --global @singularitycolabs/parallax@next
npm install --global @singularitycolabs/parallax
parallax --help
```

Or run it without a global installation:

```bash
npx --yes @singularitycolabs/parallax@next --help
npx --yes @singularitycolabs/parallax --help
```

Install the SDK in a Node.js project:

```bash
npm install @singularitycolabs/parallax@next
npm install @singularitycolabs/parallax
```

Parallax checks npm on startup and prints an upgrade line when a newer version
is out (re-run the install command above to update; disable the check with
`PARALLAX_NO_UPDATE_CHECK=1`).

## Uninstall

Parallax keeps its state in `~/.parallax` (sessions database). The CLI can clean
Expand Down Expand Up @@ -141,16 +145,36 @@ the history carries over to the new model:
> /models list models for the current provider (with price/context)
> /provider openai switch provider (uses its default model)
> /model anthropic/claude-sonnet-4-6 switch provider + model in one step
> /model gpt-4o switch model on the current provider
> /mode plan switch permission mode (or Shift+Tab to cycle)
> /model open the interactive model picker
> /tools list the available agent tools
> /theme light switch the color theme (toggles with no arg)
> /mode plan set permission mode (or /plan, /workspace, /read-only, /bypass)
> /sessions list persisted sessions
> /help show all commands
```

Keys: **Shift+Tab** cycles the permission mode (`workspace → plan → read-only`),
**Esc**/**Ctrl-C** cancels the in-flight turn (or quits when idle), **↑/↓** walk
input history, **Tab** completes a slash command. At an approval prompt, choose
**Yes**, **Yes and don't ask again** (remembers the tool for the session), or **No**.
The chosen provider/model (and theme) are remembered in
`~/.parallax/parallax.json`, and an API key entered in the `/model` picker is
saved to `~/.parallax/credentials.json` (mode 0600) by default — so the next
launch opens ready, with no reconfiguration. Environment variables still take
precedence over the saved values.

Keys: **Shift+Tab** cycles the permission mode
(`workspace → plan → read-only → bypass`), **Esc**/**Ctrl-C** cancels the
in-flight turn (or quits when idle), **↑/↓** move through the slash-command menu
(or walk input history when it's closed), **Enter/Tab** apply the highlighted
command. At an approval prompt, choose **Yes**, **Yes and don't ask again**
(remembers the tool for the session), or **No**.

Permission modes (deterministic `ALLOW / ASK / DENY`):

- **workspace** (default) — reads are allowed; writes/shell/network **ask** first.
- **plan** — research & propose: reads allowed, side effects blocked, until you
approve a plan via the `present_plan` gate (which flips you to workspace).
- **read-only** — reads only; every side effect blocked.
- **bypass** — auto-approve **everything** with no prompts. The one guardrail
that still holds: a path escaping the workspace root is always denied. The
footer turns red so this state is obvious — use it deliberately.

Resume a past session straight into the UI, transcript and all:

Expand All @@ -171,16 +195,17 @@ cp .env.example .env # then fill in your key

Config resolves as `CLI flag > env > parallax.json > built-in default`:

| Variable | Purpose | Default |
| ----------------------------------------- | --------------------------------------- | ----------------------------- |
| `PARALLAX_PROVIDER` (or `-p`) | provider id (see table above) | `fake` |
| `<PROVIDER>_API_KEY` / `PARALLAX_API_KEY` | API key for the provider | — |
| `TAVILY_API_KEY` | API key for the `web_search` tool | — |
| `PARALLAX_MODEL` (or `-m`) | model id | provider's default |
| `PARALLAX_API_BASE_URL` | override the OpenAI-compatible endpoint | provider's default |
| `PARALLAX_MODELS_URL` | models.dev catalog endpoint | `https://models.dev/api.json` |
| `PARALLAX_DISABLE_MODELS_FETCH` | use only the bundled catalog snapshot | (fetch enabled) |
| `PARALLAX_NO_TUI` | force the plain renderer on a TTY | (TUI on a TTY) |
| Variable | Purpose | Default |
| ----------------------------------------- | ----------------------------------------- | ----------------------------- |
| `PARALLAX_PROVIDER` (or `-p`) | provider id (see table above) | `fake` |
| `<PROVIDER>_API_KEY` / `PARALLAX_API_KEY` | API key for the provider | — |
| `TAVILY_API_KEY` | API key for the `web_search` tool | — |
| `PARALLAX_MODEL` (or `-m`) | model id | provider's default |
| `PARALLAX_API_BASE_URL` | override the OpenAI-compatible endpoint | provider's default |
| `PARALLAX_MODELS_URL` | models.dev catalog endpoint | `https://models.dev/api.json` |
| `PARALLAX_DISABLE_MODELS_FETCH` | use only the bundled catalog snapshot | (fetch enabled) |
| `PARALLAX_NO_UPDATE_CHECK` | skip the startup "update available" check | (check enabled) |
| `PARALLAX_NO_TUI` | force the plain renderer on a TTY | (TUI on a TTY) |

### Model catalog & custom providers (OpenCode-style)

Expand Down Expand Up @@ -243,9 +268,10 @@ approval → execute → persist → model`.
- Web tools: `web_search` (via Tavily) and `web_fetch` (URL → readable text),
classified as `network` risk with SSRF guards (localhost / private / link-local
and cloud-metadata targets are refused, redirects re-validated).
- Deterministic `ALLOW / ASK / DENY` policy with `read-only`, `workspace`, and
`plan` modes; approvals support "allow once" and "allow always" (remembered
per session).
- Deterministic `ALLOW / ASK / DENY` policy with `read-only`, `workspace`,
`plan`, and `bypass` modes; approvals support "allow once" and "allow always"
(remembered per session). `bypass` auto-approves everything but still denies
any path outside the workspace root.
- SQLite session persistence + resume (interactive or `--print`).
- A **Claude Code-like terminal UI** (React + Ink): streaming transcript, tool
blocks with live output + diffs, an interactive approval menu, a bordered
Expand Down
3 changes: 1 addition & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,7 @@
},
"publishConfig": {
"access": "public",
"registry": "https://registry.npmjs.org/",
"tag": "next"
"registry": "https://registry.npmjs.org/"
},
"dependencies": {
"commander": "^12.1.0",
Expand Down
17 changes: 17 additions & 0 deletions src/cli/agentRunner.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,17 @@ import {
} from '../app/index.ts';
import {
loadConfig,
loadLocalConfig,
databasePath,
effectiveModel,
getProvider,
refreshCatalog,
refreshUpdateInfo,
upgradeCommand,
type Config,
} from '../config/index.ts';
import type { ApprovalDecision, PermissionMode } from '../protocol/index.ts';
import type { ThemeName } from './tui/theme.ts';
import { CliRenderer } from './renderer.ts';
import {
parseCommand,
Expand Down Expand Up @@ -47,6 +51,11 @@ function buildConfig(options: AgentCliOptions): Config {
return loadConfig(overrides);
}

/** The persisted TUI theme from `parallax.json`, or `dark` when unset/invalid. */
function resolvedThemeName(): ThemeName {
return loadLocalConfig().theme === 'light' ? 'light' : 'dark';
}

function makeApprovalHandler(
yes: boolean,
rl: Interface | undefined,
Expand Down Expand Up @@ -208,6 +217,7 @@ export async function chatLoop(options: AgentCliOptions): Promise<void> {
model: desiredModel,
mode,
cwd: options.cwd,
themeName: resolvedThemeName(),
needsSetup,
});
return;
Expand All @@ -226,6 +236,12 @@ export async function chatLoop(options: AgentCliOptions): Promise<void> {
// offline run keeps the bundled snapshot.
void refreshCatalog();

// Best-effort update check (headless): print one line if a newer version is out.
void refreshUpdateInfo().then((u) => {
if (u)
process.stderr.write(`\nUpdate available ${u.current} → ${u.latest}: ${upgradeCommand(u)}\n`);
});

let activeTurn: string | undefined;
const unsubscribe = wire(agent, renderer, makeApprovalHandler(options.yes, rl), (t) => {
activeTurn = t;
Expand Down Expand Up @@ -315,6 +331,7 @@ export async function resumeChat(
model: match.model,
mode: match.permissionMode,
cwd: match.cwd,
themeName: resolvedThemeName(),
seedEvents,
});
return true;
Expand Down
7 changes: 6 additions & 1 deletion src/cli/replCommands.ts
Original file line number Diff line number Diff line change
Expand Up @@ -120,12 +120,17 @@ export function formatModels(providerId: string, currentModel?: string): string
export function formatHelp(): string {
return [
'commands:',
' /model <id> switch model (e.g. /model claude-sonnet-4-6)',
' /model [id] switch model, or open the picker (e.g. /model claude-sonnet-4-6)',
' /model <prov>/<id> switch provider + model (e.g. /model openai/gpt-4o)',
' /provider <id> switch provider, using its default model',
' /models [provider] list models for the current (or named) provider',
' /providers list providers and key status',
' /tools list the available agent tools',
' /theme [dark|light] switch the color theme (toggles if no arg)',
' /mode <mode> set permission mode (workspace|plan|read-only|bypass)',
' /workspace /plan /read-only /bypass shortcuts for each permission mode',
' /help show this help',
' /exit | /quit leave Parallax',
' exit | quit leave the REPL',
].join('\n');
}
Loading