{"_id":"@applepi-ai/applepi","name":"@applepi-ai/applepi","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@applepi-ai/applepi","version":"0.1.0","description":"Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.","type":"module","bin":{"applepi":"dist/cli.js"},"scripts":{"build":"tsc -p tsconfig.build.json && shx rm -rf dist/schemas && shx mkdir -p dist/schemas && shx cp src/schemas/*.json dist/schemas/ && shx chmod +x dist/cli.js","prepare":"npm run build","dev_install":"node scripts/dev-install.mjs","docs:dev":"npm --prefix doc_site run dev --","docs:build":"npm --prefix doc_site run build","docs:start":"npm --prefix doc_site run start --","docs:lint":"eslint doc_site --config doc_site/eslint.config.js","docs:ci":"npm --prefix doc_site ci && npm run docs:lint && npm run docs:build","typecheck":"tsc -p tsconfig.json --noEmit","lint":"eslint .","lint:fix":"eslint . --fix","test":"vitest --run","coverage":"vitest --run --coverage","snapper:format":"node scripts/run-snapper.mjs --git-md -i","check":"npm run snapper:format && prettier --write . && npm run lint:fix && npm run coverage","check-ci":"prettier --check . && npm run lint && npm run coverage && npm run docs:ci"},"dependencies":{"@earendil-works/pi-coding-agent":"^0.78.1","ajv":"^8.20.0","chalk":"^5.6.2","commander":"^14.0.3","cross-spawn":"^7.0.6","defu":"^6.1.7","glob":"^13.0.6","hosted-git-info":"^9.0.3","liquidjs":"^10.27.0","typebox":"^1.1.38","yaml":"^2.9.0"},"devDependencies":{"@eslint/js":"^10.0.1","@types/cross-spawn":"^6.0.6","@types/node":"^22.19.19","@vitest/coverage-v8":"^4.1.7","eslint":"^10.4.0","prettier":"^3.8.3","shx":"^0.4.0","typescript":"^6.0.3","typescript-eslint":"^8.60.0","vitest":"^4.1.7"},"engines":{"node":">=22.19.0"},"keywords":["agent","cli","pi","profiles"],"license":"BUSL-1.1","publishConfig":{"access":"public"},"gitHead":"a52d61e34e05e1821b1009b33bf2acc1ff6ebf1f","_id":"@applepi-ai/applepi@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-lfZyIaCxePkJj0/D/C3k4y3AQ23+F52MM/IWawB49St0a7kqBBgUsK8iTgtFpwwyZoHpypGN2TPluYxiv4mbjg==","shasum":"589b15b52b97dd569ce5affb13af2884dbf9cbe9","tarball":"https://registry.npmjs.org/@applepi-ai/applepi/-/applepi-0.1.0.tgz","fileCount":146,"unpackedSize":414445,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAvooXH/HTjxZEcemYIv5i6KngILGnPlMS2rfYHC/AecAiEAkgS5yEYAQtl7qT163Ad5NV1yvUrFwgVI2Ls3tghKNDo="}]},"_npmUser":{"name":"ncrmro","email":"ncrmro@gmail.com"},"directories":{},"maintainers":[{"name":"ncrmro","email":"ncrmro@gmail.com"},{"name":"untildesrc","email":"charlie.scherer@unsupervised.com"},{"name":"tylerwillis","email":"tyler@unsupervised.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/applepi_0.1.0_1781292061329_0.8921512566465684"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-12T19:21:01.085Z","0.1.0":"2026-06-12T19:21:01.611Z","modified":"2026-06-12T19:21:01.991Z"},"maintainers":[{"name":"ncrmro","email":"ncrmro@gmail.com"},{"name":"untildesrc","email":"charlie.scherer@unsupervised.com"},{"name":"tylerwillis","email":"tyler@unsupervised.com"}],"description":"Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.","keywords":["agent","cli","pi","profiles"],"license":"BUSL-1.1","readme":"_pre-launch | internal tool preview._\n\n# applepi\n\n`applepi` is intended to be a management wrapper for launching [`pi`](https://github.com/earendil-works/pi-coding-agent) and Claude Code with configurable, reusable profiles.\n\nThe goal is manageable agent CLI configuration:\n\n- Organizations can define standard pi or claude loadouts, share them, and launch agent CLIs consistently across different environments.\n- Individuals can swap between configurations of their coding agent, share those, and easily migrate to new machines.\n\nIf you haven't tried [Pi](https://pi.dev) yet — we think it's a great coding harness & ApplePi is an easy way to try it.\n\n- Install and run `applepi` to load pi with our standard configuration for engineers.\n\n## Install\n\n### Agent-assisted setup\n\nUsing a CLI coding agent (Claude Code, pi, etc.)? Copy this prompt and paste it into your agent:\n\n<details>\n<summary>Setup prompt</summary>\n\n```text\nInstall applepi globally from npm with `npm install -g @applepi-ai/applepi`.\nVerify the `applepi` command is on PATH. Then check whether the pi coding\nagent (https://github.com/earendil-works/pi-coding-agent) is installed; if\nnot, install it per its README. Report what was installed and any PATH\nchanges I need. If global npm registry installation is unavailable, clone\nhttps://github.com/applepi-ai/applepi into a sensible location (e.g. ~/repos),\nrun npm install, then npm run dev_install.\n```\n\n</details>\n\n### Manual install\n\nInstall ApplePi from npm:\n\n```bash\nnpm install -g @applepi-ai/applepi\n```\n\nFor source development, clone the repository and link the local checkout:\n\n```bash\ngit clone https://github.com/applepi-ai/applepi\ncd applepi\nnpm install\nnpm run dev_install\n```\n\n`npm run dev_install` builds the CLI and links it globally via `npm link`, so `applepi` is on your PATH and rebuilds in this checkout take effect immediately.\n\nApplePi launches agent CLIs but does not install them. Install the agents you plan to use separately:\n\n- [pi](https://github.com/earendil-works/pi-coding-agent) — follow its installation instructions; the `pi` command must be on your PATH.\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — only needed if you launch with `--agent claude`.\n\n## Why this exists\n\nPi is highly configurable through settings directories, extensions, skills, prompts, themes, model settings, environment variables, and CLI flags.\nThat flexibility is powerful, but businesses often need a higher-level control plane for repeatable deployments.\n\n`applepi` should make it easy to answer questions like:\n\n- Which pi configuration should this employee or team use?\n- Which extensions, skills, prompts, models, and providers are approved?\n- Which credentials or environment variables should be present?\n- Should project-local `.pi` configuration be allowed, merged, or ignored?\n- How do we ship multiple standardized pi loadouts without manual setup?\n\n## Intended use case\n\nExample profile concepts:\n\n- `engineering-default` — standard engineering loadout with approved tools, prompts, and models.\n- `support` — customer-support-focused prompt and restricted tool set.\n- `sandbox` — isolated experimentation profile with disposable config and sessions.\n- `regulated` — locked-down profile with stricter extensions, context, and session behavior.\n\nA launch flow is intended to look like:\n\n```bash\napplepi\napplepi run --profile engineering-default\napplepi run -p support -- --cwd ~/work/customer-issue\napplepi sync\napplepi setup\napplepi setup https://github.com/my_account/applepi_config\napplepi profile list\napplepi profile create regulated --scope user\n```\n\nUnder the hood, `applepi` translates a selected profile into the selected agent launch environment.\nPi runs use `PI_CODING_AGENT_DIR`; Claude Code runs use `CLAUDE_CONFIG_DIR`; both receive supported CLI flags, prompts, model settings, and environment variables.\nSelect the adapter with `applepi run --agent <pi|claude>`, or set `default_agent` in `settings.yml`.\nIf neither is set, ApplePi defaults to pi for backward compatibility.\nIf `applepi` is run before `applepi setup`, it creates the initial settings and default profile automatically before launching.\n\n`settings.yml` can point at local profiles, full Git URIs, or GitHub shorthand sources with optional refs and repository subpaths:\n\n```yaml\nremote_settings:\n  - github: my_account/applepi_config\n    ref: main\n    path: settings.yml\n\nprofile_sources:\n  - github: my_account/applepi_config\n    ref: main\n    path: profiles\n```\n\nRun `applepi sync` to fetch/update remote settings and profiles before using them.\n\nBy default, ApplePi keeps reusable runtime cache files under `~/.applepi/cache`.\nSet `cache_directory` in `settings.yml` to choose a different cache root; relative values resolve from the settings file that declares them.\nThe pi adapter symlinks composite profile `utilities/` and `bin/` paths into this cache so pi-managed utilities such as `fd` and `rg` survive across temporary composite profile directories.\n\nSettings can also define arbitrary nested `custom_settings` values for ApplePi-time composite profile templating:\n\n```yaml\ncustom_settings:\n  build_commands:\n    lint: npm run lint\n```\n\nGenerated composite profile files can reference them with ApplePi's LiquidJS-based custom delimiters:\n\n```yaml\ncommand: '[[= applepi.custom_settings.build_commands.lint ]]'\n```\n\nControl tags use `[[% ... %]]`, for example `[[% for item in applepi.custom_settings.items %]]`.\nApplePi intentionally does not use common `{{ ... }}` delimiters, and plain shell expressions like `[[ -f package.json ]]` are left alone.\n\n## Setup from a settings repository\n\nYou can bootstrap a machine from a Git repository:\n\n```bash\napplepi setup https://github.com/my_account/applepi_config\n```\n\n`applepi setup` requires an interactive terminal on both stdin and stdout.\nWhen a repository is provided, it clones or updates the repository in ApplePi's shared repository cache, then uses it as a non-overwriting starting point:\n\n- if `~/.applepi/settings.yml` does not exist, ApplePi copies the starter `settings.yml`;\n- if starter profiles exist, ApplePi copies missing profile files into `~/.applepi/profiles/`;\n- existing user settings and profile files are otherwise left unchanged;\n- after setup, ApplePi runs the same sync behavior used by `applepi sync`;\n- ApplePi then shows a short setup wizard that lists synced profiles and writes the selected default profile to user settings.\n\nA setup repository can use either root-level ApplePi files:\n\n```text\napplepi_config/\n  settings.yml\n  profiles/\n    engineering-default/\n      profile.yml\n    support/\n      profile.yml\n```\n\nor a `.applepi/` layout:\n\n```text\napplepi_config/\n  .applepi/\n    settings.yml\n    profiles/\n      engineering-default/\n        profile.yml\n      support/\n        profile.yml\n```\n\nExample `settings.yml` for a setup repository:\n\n```yaml\ndefault_profile: engineering-default\n\nprofile_sources:\n  - path: ./profiles\n\n  # Optional: keep loading future updates from this same repo.\n  - github: my_account/applepi_config\n    ref: main\n    path: profiles\n```\n\nIf you want ongoing centralized settings, use a small local `~/.applepi/settings.yml` that points at remote settings:\n\n```yaml\nremote_settings:\n  - github: my_account/applepi_config\n    ref: main\n    path: settings.yml\n```\n\nThen run:\n\n```bash\napplepi sync\n```\n\n## Profile model sketch\n\nA profile will use YAML.\nAn initial profile shape is:\n\n```yaml\nid: engineering-default\nlabel: Engineering Default\ninherits:\n  - base-typescript\n\ncontrols:\n  model: anthropic/claude-sonnet-4\n  environment:\n    TEAM_MODE: engineering\n```\n\nThe exact stable schema is governed by the requirements in `requirements/` and the JSON Schema files in `src/schemas/`, which are still expected to evolve with implementation.\n\n## Design direction\n\nThe current recommendation is to build `applepi` around pi's existing native configuration mechanisms:\n\n1. Use a temporary composite profile directory as `PI_CODING_AGENT_DIR` for each run.\n2. Persist intentional pi state through adapter-declared symlinks to profile, native pi, or ApplePi cache files. Native pi fallback is only a durable target for declared state symlinks; it is not an inherited base profile layer.\n3. Layer profile-controlled environment variables and pi CLI flags on top.\n4. Use explicit `--extension` / `-e` injection for bootstrap behavior that needs to run inside pi.\n5. Decide per profile whether project-local `.pi` overrides are allowed.\n6. Keep the wrapper responsible for anything that must happen before pi starts, such as selecting config directories, setting credentials, or choosing session locations.\n\nSee [`recommendation.md`](./recommendation.md) for current notes on pi startup behavior and wrapper strategy.\n\n## Status\n\nThis repository is under phased implementation.\n\nA minimal executable CLI exists, with initial settings/profile schemas, local and URI-backed profile loading, profile resolution internals, first-pass `setup`, `sync`, `profile list`, and `profile create` commands, and a first-pass `run` command for assembling a temporary composite profile and launching pi or Claude Code.\nStable end-to-end pi launch behavior and user-facing examples will be hardened in a later phase.\nThe initial dependency and architecture decisions are documented in `package.json`, `doc/architecture.md`, and `requirements/`.\n\n## Future work\n\n- Define a stable profile schema.\n- Decide where organization-managed profiles are discovered from.\n- Harden stable `applepi run --profile <profile>` behavior.\n- Add validation and inspection commands.\n- Expand user-facing documentation for resolved profile inheritance and composition.\n- Add locking / policy controls for business-managed environments.\n- Add examples for common organizational deployments.\n","readmeFilename":"README.md","_rev":"1-4f8818eb0cd0328c749720ffdf6b757f"}