Envit

envit — repo context for agents

envit is a virtualenv for repo context. The project's envit.json declares which git repositories an agent should be able to read; envit sync materializes them, read-only and commit-pinned, under .envit/repos/. The bytes live once per machine in a shared store — never edit them, and never commit .envit/ (it's gitignored; the manifest and envit.lock.json are committed instead).

Reading context (the common case — no commands needed)

1. Read .envit/AGENTS.md first: it lists every available repo, its commit, and its resolved path.
2. Dependency source lives at .envit/repos/<name>/ — real, complete, at the exact commit the lockfile pins. Prefer reading it over guessing at a library's behavior from memory.
3. The entries are symlinks: rg and fd skip them by default. Use rg --follow / fd -L, or search the resolved store path from AGENTS.md (generated) directly.
4. Everything is read-only by design. If you need to modify a dependency, that's a fork/vendor decision for the user — say so instead of fighting the permissions.

If .envit/repos/ is missing but envit.json exists, run envit sync.

Commands

Env vars: ENVIT_HOME (store location, default ~/.envit), ENVIT_NO_REFRESH=1 (block all implicit refresh), ENVIT_REFRESH_TTL (e.g. "1h", global staleness window).

Manifest format (envit.json)

JSON: a list of repo links, plus an optional skills object. A bare "owner/repo" string means GitHub at the default branch; an entry needing options becomes an object:

{
  "repos": [
    "tokio-rs/tokio",
    { "source": "Effect-TS/effect", "ref": "next" },
    { "source": "serde-rs/serde", "ref": "v1.0.200", "update": "frozen" }
  ],
  "skills": {
    "vercel-labs/agent-skills": ["web-design-guidelines"]
  }
}

Per-entry keys: source (required), name, ref, update (auto/manual/frozen), ttl (e.g. "1h"), history ("full"). Skills sources also take path (subdirectory in a monorepo) and modelInvocable (true/false): whether the model may invoke the skill on its own. Overrides the author's controls for both Claude (disable-model-invocation) and Codex (allow_implicit_invocation). Applies per source, or per skill via { "name": ..., "modelInvocable": ... } in a pick list. Prefer envit add/remove/pin over hand-editing; CLI edits re-emit canonical pretty-printed JSON.

Situations and the right move

You need source the project doesn't declare yet (debugging into a library, checking an API): envit add github:owner/repo && envit sync. Tell the user you added it — it edits their committed manifest.

Context changed under you mid-task (files shifted after a sync advanced a branch): envit pin <name> freezes the repo at the commit you're looking at, instantly. Note the pin in your summary so the user knows to unpin later.

Context looks stale (the lockfile commit is weeks old and you need newer code): envit update <name>. Never assume freshness — envit status shows what's pinned and when remotes were last checked.

Bootstrapping a fresh checkout or sandbox: envit sync --frozen gives bit-identical context to the committed lockfile. This is the only sync mode CI and cloud environments should use.

Merge conflict in envit.lock.json: don't hand-merge — resolve the manifest, then run envit sync; the lock is machine-regenerated canonically.

Semantics worth knowing

• The manifest is intent ("track main"); envit.lock.json is fact ("main was 3f2a9c1 when materialized"). Both are committed.
• Plain sync does not chase branches — a locked repo stays put unless it is auto (the default) and its remote hasn't been checked in 24h. update is the explicit "move now."
• Checkouts are keyed by commit SHA in the store, so two projects pinned to different commits coexist and nothing changes behind a project's back. Refreshes swap the symlink atomically.
• envit runs no daemons; nothing happens between invocations.

If the envit binary is not on PATH, ask the user how it is installed in this environment (in envit's own development repo it is target/release/envit after cargo build --release).