Getting Started

Getting Started

Prerequisites

• Rust toolchain (edition 2021, MSRV 1.75)
• A coding agent that reads AGENTS.md (Claude Code, Cursor, Windsurf, Codex, Gemini CLI)

Build from source

git clone https://github.com/Ghost-Frame/FrameShift.git
cd FrameShift
cargo build --release

The CLI binary lands at target/release/frameshift-cli.

Install and activate a persona

The fastest path is frameshift use, which installs, activates, and prints the rendered persona in one call:

frameshift use cryptographic --from ./personas

Or step by step:

# Install a specific version from a local directory:
frameshift install cryptographic@0.1.0 --from-path ./personas/cryptographic

# Activate it for the current project:
frameshift activate cryptographic

What happens on install

1. The CLI reads the persona's pack.toml manifest.
2. It computes a deterministic SHA-256 hash of the pack contents (canonical directory walk with unicode normalization).
3. It copies the pack into the content-addressed cache at $XDG_DATA_HOME/frameshift/cache/<hash>/.
4. It records the persona in the project's lock.toml with the exact version, hash, and author public key.
5. It renders the persona source into per-agent markdown under rendered/{claude,codex,gemini,generic}/.

Your project tree is never written to. All state lives under $XDG_DATA_HOME/frameshift/.

Verify the installation

# Print the hashed project ID:
frameshift project-id

# Check what's installed:
frameshift sync

Run from source (without installing the binary)

cargo run -p frameshift-cli -- use cryptographic --from ./personas
cargo run -p frameshift-cli -- select --task "optimize a hot loop" --format json

Next steps

• Automate Mode -- Let the engine pick personas automatically
• CLI Reference -- Full command reference
• Writing Personas -- Create your own