lairen 来人

Bring the right CLI-agent identity to the right place.

lairen is a Python credential registry and deployer for CLI coding agents. It stores a provider login once, then materializes it into any target home on demand — project-local, holder directories, or throwaway worktrees.

Status: 0.1.0, Pixi-managed, Click-based. Codex and Kimi are the tested adapters; the other provider adapters are implemented but remain experimental because this project has no live credentials for them yet. Remote quota queries and OAuth refresh are the next milestones.

Why

• Keep credentials out of project repos and out of a single global home.
• Deploy a saved login into an arbitrary provider home.
• Preserve session-level Kimi identity: (user_id, device_id), not just user_id, so independent logins of one account stay addressable.
• Inspect expiry and usage from one command, including machine-readable JSON.
• Use explicit CLI arguments first; common provider environment variables are respected only as fallbacks.

Requirements

• Python >=3.11 (the Pixi environment pins the 3.11 line)
• Pixi for the managed development environment
• Click for the CLI

Install

pixi install
pixi run lairen --help

A plain editable install works too:

python -m pip install -e .
lairen --help

Quick start

Codex and Kimi are the tested paths:

# Register a Codex home (reads auth.json, never prints tokens)
pixi run lairen register codex --home ~/codex-holder/.codex

# Register a Kimi home (reads credentials/kimi-code.json)
pixi run lairen register kimi --home ~/kimi-homes/kimi-2064-1

# List saved identities
pixi run lairen list

# Deploy a saved login into a project-local home
pixi run lairen deploy codex/alice@example.com --home ./my-project/.codex

# Usage / expiry report (alias: stats)
pixi run lairen usage
pixi run lairen usage kimi/alice--device-id --json

Provider surface

lairen exposes every provider surface that subswap supports. Adapters marked tested=no are implemented against the upstream storage layouts but have not been exercised with live credentials here.

Provider home resolution order:

1. --home <path>
2. the provider environment variable (CODEX_HOME, KIMI_CODE_HOME, ...)
3. the provider default

Deployment always requires an explicit --home; lairen does not infer a target from an environment variable.

Commands

<ref> is provider/id (for example codex/alice@example.com or kimi/alice--<device-id>). A bare id or label is accepted when it is unique.

Storage

~/.config/lairen/
  registry.json          # account metadata: provider, id, label, source
~/.local/share/lairen/
  credentials.json       # credential blobs, mode 0600
  state/snapshots/       # pre-deploy copies of overwritten target files

Set LAIREN_HOME=/absolute/path to keep config, data, and state under one root. This is a development and testing override, not an input mechanism for provider selection.

Design

• Registry and credentials stay separate. Metadata is readable; secrets live in one 0600 JSON file.
• Deployment is atomic. Target files are written through a temporary file and os.replace, with a pre-deploy snapshot when the target already exists. Provider-specific adapters merge rather than replace where upstream expects it (OpenCode Go slot, Cursor ItemTable, Claude oauthAccount).
• Kimi identity is a session. user_id plus device_id, joined as user_id--device_id, so multiple logins of one account remain distinct.
• Usage is local-first. lairen usage reports token expiry and refresh timestamps from stored blobs. Remote quota endpoints plug in behind Provider.local_usage() later.

Development

pixi run test        # core + aux unit/integration suites
pixi run test-core   # tests for src/lairen
pixi run test-aux    # tests for repository support files
pixi run lint
pixi run typecheck

Codex and Kimi are the only adapters with live-credential tests. Other adapters use fake payloads or remain untested until credentials are available.

Project layout

• src/lairen/: importable package and Click CLI
• tests/core/: tests for distributed code (unit, integration, manual)
• tests/aux/: tests for repository support content
• extern/: tracked, orphan, and linked-worktree external material
• context/: plans, features, design, summaries, and archived context
• docs/: user-facing documentation source
• scripts/: repository automation outside the installed package
• skillset/: project-specific agent skills

Security

Credential files are stored in plaintext with 0600 permissions, matching the native clients. Do not commit credentials.json, registry.json, or any provider home. Rotating OAuth refresh tokens cannot be safely shared by two active homes at once; prefer one active home per saved session.

Limitations

• Remote quota queries and OAuth refresh/write-back are not implemented.
• cursor requires Cursor to be closed while the SQLite database is updated.
• opencode covers the Go API-key slot; Console account switching stays with the official CLI.
• claude, commandcode, cursor, and opencode are experimental until live-credential tests are added.

License

MIT