Skip to main content

Getting Started with llmenv

llmenv is a universal, scope-aware environment for AI coding agents. It detects your current context (network, host, user, project), selects the matching configuration, materializes it into an agent-native config directory, and points the agent at it — automatically, from a shell hook.

This page takes you from zero to a working setup. For the conceptual model, read Concepts afterward.

1. Install​

Latest release:

cargo install llmenv

From source:

git clone https://github.com/phaedrus1992/llmenv.git
cd llmenv
cargo build --release
./target/release/llmenv --help

2. Initialize configuration​

llmenv init

This writes a template config.yaml into your config directory (~/.config/llmenv/config.yaml, or $LLMENV_CONFIG_DIR if set). It won't overwrite an existing config. To start from an existing config repository instead:

llmenv init --repo https://github.com/you/llmenv-config.git

3. Install the shell hook​

The hook runs llmenv export on every prompt, keeping the environment in sync as you move between directories and networks.

zsh — add to ~/.zshrc:

eval "$(llmenv hook zsh)"

bash — add to ~/.bashrc:

eval "$(llmenv hook bash)"

Reload your shell (exec zsh / exec bash) or open a new terminal. To preview what the hook installs without committing to it, just run llmenv hook zsh and read the output.

4. Verify the setup​

llmenv doctor

doctor checks:

  • configuration parsing,
  • cache directory writability,
  • git remote connectivity,
  • orphans — scopes/tags/bundles/MCP/plugins that can never activate, a memory server_host missing from host:, and unknown fields in project markers.

Then inspect what resolves for your current directory:

llmenv status        # active scopes + tags, parse status
llmenv context       # the fuller resolved view
llmenv export        # the actual export lines the hook runs

5. Add a project​

Per-project configuration lives in a .llmenv.yaml marker at the project root — not in config.yaml. Drop one in and llmenv discovers it by walking the current directory upward to $HOME:

# ~/code/myapp/.llmenv.yaml
id: myapp
name: MyApp
description: "Customer-facing API"
tags: [myapp, rust]
enable_bundles: [base]      # optional: force-enable bundles regardless of tags

cd into the project and run llmenv context — you should see the project scope active and its tags joined to the set.

Minimal config example​

cache:
  cache_dir: "~/.cache/llmenv"
  sync_interval_minutes: 60

scope:
  network:
    - id: office
      match: { gateway_mac: "aa:bb:cc:dd:ee:ff" }
      tags: [office]
  user:
    - id: me
      match: { user: "alice" }
      tags: [me]

bundle:
  - name: base
    tags: [me]
    vars:
      EDITOR: "code"

See Configuration for the complete schema.

Commands reference​

CommandPurpose
llmenv init [PATH] [--repo URL]Initialize configuration
llmenv export [--scope ID] [--tag TAG]Export environment variables
llmenv hook <zsh|bash>Generate shell hook code
llmenv statusShow active scopes/tags + parse status
llmenv contextShow the resolved environment in detail
llmenv scope-ls / tag-ls / bundle-lsList scopes / tags / bundles
llmenv mcp-lsList selected MCP servers
llmenv marketplace-ls / plugin-lsList marketplaces / plugins
llmenv plugin-syncSync plugin marketplaces into the cache
llmenv syncCommit and push config to GitHub
llmenv check-staleWarn if the running agent's config drifted
llmenv prune [--all] [--older-than DUR] [--dry-run]Clean stale cache folders
llmenv doctor [--gc]Run diagnostics (optionally GC)

Full per-command reference: commands.md.

Common first errors​

  • "Config already exists" from init — expected; init never overwrites. Edit ~/.config/llmenv/config.yaml directly.
  • Nothing activates — your scopes' tags don't match any contributor's tags, or no scope matches your environment. Run llmenv scope-ls and llmenv tag-ls (active items are marked) and check Troubleshooting.
  • YAML parse error — usually an unquoted value containing a colon. Quote addresses, MACs, SSIDs, and URLs. See Configuration → YAML gotchas.
  • Network scope never matches — only gateway_mac is evaluated today; ssid/cidr are ignored. Use a host scope as a reliable fallback.

Next steps​