Skip to main content

FAQs

Questions about the harness

Short answers. For the turn loop and tool model, see the docs and the GitHub README.

What is Elph?

An opinionated AI coding agent harness that runs locally. The session loop follows Pi; Elph adds a local store, floppy memory, worktrees, MCP, and extra surfaces. Interactive TUI (elph), headless prompts (elph run), and ACP for editors (elph acp --stdio).

Is Elph stable?

No. Elph is pre-alpha. Breaking changes and bugs are expected. Always read the release notes before you upgrade.

How do I install it?

Prebuilt Linux and macOS binaries (x86_64 and arm64): 

curl -fsSL https://elph.space/install.sh | bash

Or cargo install --locked elph with Rust ≥ 1.97.

Which models can I use?

Any catalog in elph-ai: OpenAI, Anthropic, Gemini, xAI, OpenRouter, GitHub Copilot, Amazon Bedrock, Groq, DeepSeek, Hyper, and local OpenAI-compatible endpoints. Switch mid-session with elph provider / elph models. OAuth where the provider supports it.

Where does Elph store data?

Config under ~/.config/elph/ (or ELPH_HOME). Project sessions and memory live in .elph/store.db — Turso / SQLite with FTS and vectors. There is no required cloud agent backend.

How do I attach an editor?

elph acp --stdio speaks Agent Client Protocol v1. Pass --experimental for ACP v2. The TUI remains the default surface; ACP is the editor bridge.

Can I run Elph without the TUI?

Yes. elph run "…" is headless. Output formats include plain, pretty, json, stream-json, and Anthropic-style stream-message-json. Plan mode and turn limits are available as flags.

How do approvals work?

Risky shell and file actions stay visible. Plan mode designs and asks; approved plans land in .elph/plans/ before the full Build tool surface returns. Workspace trust is recorded in trust.json.

Can I import a Claude or Codex session?

elph import reads those transcripts as inert context. Foreign tool calls are not executed. That safety boundary is intentional.

How do I extend it?

MCP servers (stdio and streamable HTTP) via elph mcp, WASM extensions via wasmi (elph extensions), and SKILL.md packages. The MIT crates — elph-ai, elph-agent, elph-tui, floppy — are the embeddable runtime.

What license is Elph under?

The elph application is Apache-2.0. Libraries are MIT. Third-party attributions live in NOTICE.md. The project is actively developed — check release notes before you upgrade.