Skip to content

quickstart.md

Latest commit

 

History

History
165 lines (105 loc) · 4.61 KB

quickstart.md

File metadata and controls

165 lines (105 loc) · 4.61 KB
Raw

Quickstart

This page gets you from install to a useful first offsidepi session.

Install

offsidepi is distributed as an npm package:

npm install -g --ignore-scripts @offsideai/offsidepi-coding-agent

--ignore-scripts disables dependency lifecycle scripts during install. offsidepi does not require install scripts for normal npm installs.

Uninstall

Use the package manager that installed offsidepi. The curl installer uses npm globally, so curl and npm installs are removed with npm:

# curl installer or npm install -g
npm uninstall -g @offsideai/offsidepi-coding-agent

# pnpm
pnpm remove -g @offsideai/offsidepi-coding-agent

# Yarn
yarn global remove @offsideai/offsidepi-coding-agent

# Bun
bun uninstall -g @offsideai/offsidepi-coding-agent

Uninstalling offsidepi leaves settings, credentials, sessions, and installed offsidepi packages in ~/.offsidepi/agent/.

Then start offsidepi in the project directory you want it to work on:

cd /path/to/project
offsidepi

Authenticate

offsidepi can use subscription providers through /login, or API-key providers through environment variables or the auth file.

Option 1: subscription login

Start offsidepi and run:

/login

Then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot.

Option 2: API key

Set an API key before launching pi:

export ANTHROPIC_API_KEY=sk-ant-...
offsidepi

You can also run /login and select an API-key provider to store the key in ~/.offsidepi/agent/auth.json.

See Providers for all supported providers, environment variables, and cloud-provider setup.

First session

Once offsidepi starts, type a request and press Enter:

Summarize this repository and tell me how to run its checks.

By default, offsidepi gives the model four tools:

  • read - read files
  • write - create or overwrite files
  • edit - patch files
  • bash - run shell commands

Additional built-in read-only tools (grep, find, ls) are available through tool options. offsidepi runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.

Give offsidepi project instructions

offsidepi loads context files at startup. Add an AGENTS.md file to tell it how to work in a project:

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

offsidepi loads:

  • ~/.offsidepi/agent/AGENTS.md for global instructions
  • AGENTS.md or CLAUDE.md from parent directories and the current directory

Restart offsidepi, or run /reload, after changing context files.

Common things to try

Reference files

Type @ in the editor to fuzzy-search files, or pass files on the command line:

offsidepi @README.md "Summarize this"
offsidepi @src/app.ts @src/app.test.ts "Review these together"

Images can be pasted with Ctrl+V (Alt+V on Windows) or dragged into supported terminals.

Run shell commands

In interactive mode:

!npm run lint

The command output is sent to the model. Use !!command to run a command without adding its output to the model context.

Switch models

Use /model or Ctrl+L to choose a model. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.

Continue later

Sessions are saved automatically:

offsidepi -c                  # Continue most recent session
offsidepi -r                  # Browse previous sessions
offsidepi --name "my task"    # Set session display name at startup
offsidepi --session <path|id> # Open a specific session

Inside offsidepi, use /resume, /new, /tree, /fork, and /clone to manage sessions.

Non-interactive mode

For one-shot prompts:

offsidepi -p "Summarize this codebase"
cat README.md | offsidepi -p "Summarize this text"
offsidepi -p @screenshot.png "What's in this image?"

Use --mode json for JSON event output or --mode rpc for process integration.

Next steps

  • Using offsidepi - interactive mode, slash commands, sessions, context files, and CLI reference.
  • Providers - authentication and model setup.
  • Settings - global and project configuration.
  • Keybindings - shortcuts and customization.
  • offsidepi Packages - install shared extensions, skills, prompts, and themes.

Platform notes: Windows, Termux, tmux, Terminal setup, Shell aliases.