overlane weekly downloads statistics

Overlane

Overlane connects a GitHub project to your coding agents. One connection gives Claude Code, Codex and background bots project memory, tasks, a code map, guardrails and evidence that work is really done.

This package is the overlane command line: connect and doctor, tasks and runs, releases, the code indexer (overlane index), the local code shim (overlane shim, off by default) and the Claude Code and Codex plugin (overlane plugin install).

Node 22 or later. No runtime dependencies: the package is one bundled file plus its assets, and works offline after install. The hosted service is not in the package. Docs: https://docs.overlane.app.

Install

npm i -g overlane

Or from a GitHub release tarball (every release attaches overlane-<version>.tgz):

npm i -g https://github.com/overlanedev/overlane/releases/download/v<version>/overlane-<version>.tgz

Check it:

overlane --version
overlane help

The binary is overlane; ol is the short alias.

The package version is the plugin release version, so the plugin you install always matches the binary.

Quick start

In a git repository:

overlane connect            # sign in, bind the project to the service, register the plugin for this project
overlane plugin install     # install the embedded plugin for Claude Code (and Codex, when `codex` is on PATH)
overlane doctor             # check that each agent is ready

overlane connect reads the plugin marketplace from a stable folder under your data directory ($XDG_DATA_HOME/overlane/marketplace, default ~/.local/share/overlane/marketplace; OVERLANE_DATA_DIR overrides the base). The package writes that folder from its embedded release the first time connect, doctor or release runs, so no separate step is needed before connect. The folder and the plugin id overlane keep their names for now so existing installs keep working.

overlane plugin install [--scope project|user] [--client claude|codex]:

1. verifies every embedded plugin file against the embedded release manifest (sha256 per file and the release digest) and refuses to install if anything differs;
2. copies the tree into the stable marketplace folder and verifies the copy;
3. runs the clients' native commands: claude plugin marketplace add, claude plugin marketplace update, claude plugin install overlane@overlane-local --scope <scope>, and for Codex codex plugin marketplace add and codex plugin add (Codex only when codex is on PATH).

The default scope is user. Use --scope project to write the plugin into the current project's .claude/settings.json. The signature on a release is checked by overlane release update against the service key; the embedded manifest is checked for integrity only.

Credentials: the npm package has no OS keychain module, so overlane connect keeps tokens in a 0600 file under $XDG_CONFIG_HOME/overlane (default ~/.config/overlane). Nothing is written to the repository.

For AI agents

overlane is built to be driven by an agent. Start here:

overlane context                 # one JSON briefing: auth, project, release, task, run, policy, next task, suggested commands
overlane search "<task>"         # local, no credentials: the 5 best commands for a task, as JSON
overlane schema <command>        # parameters (type, required, description), safety flags, result shape
overlane commands                # every command, with its effect: read, write or destructive

• Output. JSON on stdout when stdout is not a terminal or with --json; text in a terminal or with --text. Messages go to stderr (--verbose keeps progress in JSON mode). A write with nothing to return prints {"ok":true}.
• Errors are {"error":{"code","message","hint","retryable"}} on stderr; hint is the exact next command. Exit codes: 0 ok, 1 failure, 2 usage, 3 auth required, 4 not found, 5 conflict or precondition, 6 blocked by policy or budget, 7 service unreachable. Messages never contain a credential.
• Safety. Every write takes --dry-run, which prints the requests it would send (method, path, body) and the files it would change, and needs no credentials. Destructive commands (disconnect, release rollback) need --force when stdin is not a terminal. Nothing prompts without a terminal.
• Auth. A person signs in with overlane auth login (a browser flow); an agent with no person present signs in with overlane auth login --repo, which proves write access to the project's repository and stores a one-hour token. No token is read from the environment or pasted anywhere. overlane auth status reports the state without revealing the token.
• Unknown commands suggest the closest matches.

Add this block to AGENTS.md or CLAUDE.md (overlane agents-md prints it):

<!-- overlane:cli:begin -->
## Overlane

Agents: run `overlane context`, then `overlane search "<task>"`. `overlane schema <command>` gives exact flags; output is JSON when piped; exit codes: 0 ok, 2 usage, 3 auth, 4 not found, 5 conflict, 6 blocked by policy or budget, 7 unreachable; use `--dry-run` before a write.
<!-- overlane:cli:end -->

Cloud sessions

The plugin hooks are Node scripts inside the installed plugin (node ${CLAUDE_PLUGIN_ROOT}/scripts/...); they need Node 22 and the plugin, not network access at install time. The overlane binary installs and updates the plugin and is what the agent calls for overlane task .... Pin the version so a cloud session installs the same release every time.

Claude Code on the web

In the environment's setup script:

npm i -g overlane@<version>
overlane plugin install --client claude --scope user…