Skip to content

install_and_profiles.md

Latest commit

 

History

History
276 lines (201 loc) · 10.9 KB

install_and_profiles.md

File metadata and controls

276 lines (201 loc) · 10.9 KB
Raw

Install And Profiles

Recommended Install

uv tool install git+https://github.com/nshkrdotcom/atlas_once
atlas install

Use the CLI directly after install:

atlas

Optional shell helper setup:

atlas config shell install

That installs the managed d helper for docday.

MCP Client Setup

Atlas ships atlas-mcp, a stdio MCP server for Codex and other MCP-capable clients. Generate the Atlas-owned client snippet with installer commands:

uv tool install git+https://github.com/nshkrdotcom/atlas_once
atlas install --profile nshkrdotcom
atlas config mcp install
atlas config mcp show
atlas config mcp doctor
codex mcp add atlas-once --env ATLAS_ONCE_PROFILE=nshkrdotcom -- atlas-mcp

The snippet uses the stable atlas-mcp console command. It is written under Atlas-managed config paths and does not mutate a global client config unless a future client-specific command documents that behavior explicitly. The same command installs the packaged atlas-codex skill asset under Atlas-managed MCP config for client onboarding. For local checkout development, use uv tool install --reinstall /path/to/atlas_once to update the installed commands from a checkout. uv run atlas ... does not install atlas-mcp for Codex.

Packaged Profiles

Atlas Once currently ships:

  • default
  • nshkrdotcom

Inspect them:

atlas config profile list
atlas config profile show default
atlas config profile show nshkrdotcom

Install with a specific profile:

atlas install --profile default
atlas install --profile nshkrdotcom

Switch later:

atlas config profile use default

The installed default remains nshkrdotcom.

Ranked Config Seeding

atlas install and atlas config profile use <name> both seed the managed ranked-context config for the active profile and enqueue every configured ranked group for background snapshot warming. The shipped config is repo-owned. If the packaged defaults change, reapply them with atlas config ranked install --force instead of hand-copying local edits.

Useful commands:

atlas --help-full
atlas config ranked path
atlas config ranked show
atlas config ranked install --force
atlas context ranked groups
atlas context ranked repos gn-twelve
atlas context ranked warm gn-twelve
atlas context ranked gn-twelve --amount mctx-all
atlas context ranked ~/p/g/n/jido_integration --amount mctx-all
atlas config ranked group add my-slice app_kit:gn-ten AITrace
atlas config ranked group show gn-twelve
atlas config ranked group copy gn-twelve my-gn

The shipped nshkrdotcom template now seeds:

  • owned-elixir-all for self-owned primary Elixir repos under ~/p/g/n
  • gn-ten for the preserved ten-repo workspace slice
  • gn-eleven for the preserved slice that adds Chassis
  • gn-twelve for the recommended slice that also adds Synapse

gn-twelve is the personal default sample config and currently expands to:

  • app_kit
  • extravaganza
  • mezzanine
  • outer_brain
  • citadel
  • jido_integration
  • execution_plane
  • ground_plane
  • stack_lab
  • AITrace
  • chassis
  • synapse

The ranked defaults are budget-first:

  • byte budget via max_bytes
  • estimated token budget via max_tokens
  • project ordering via priority_tier
  • Weld-aware project selection for the large monorepos that publish projected artifacts

The same ranked pipeline also supports ad-hoc paths. When a workspace root already contains multiple Mix projects, atlas context ranked <path> uses the path directly instead of requiring a managed group. The ranked controls are the same for groups and paths: --amount, --portion, --projects, --files, --select, --max-tokens, --max-bytes, and --no-budget.

gn-twelve default output is curated policy, not a fixed percentage. Use atlas context ranked gn-twelve --amount mctx-all when you want the blunt-force Mix context mode: all discovered Mix projects, mix.exs/README.md/lib/**/*, full deterministic selection, and no preset byte/token budget.

gn-twelve is not a special case in the CLI. It is a managed group from the packaged nshkrdotcom ranked config. It preserves the gn-ten and gn-eleven groups, reuses chassis:gn-eleven, and selects synapse:gn-twelve. The Synapse policy caps the repo at 140,000 bytes/35,000 estimated tokens, gives the headless product core a 70,000-byte project budget, and gives the web shell a 60,000-byte project budget. New groups can reuse the original variants with refs like citadel:gn-ten and jido_integration:gn-ten; refs without a suffix use the default repo variant.

Typical ranked flow after install:

atlas registry scan
atlas index watch --once
atlas context ranked groups --names
atlas context ranked repos gn-twelve
atlas context ranked warm gn-twelve
atlas context ranked plan gn-twelve --amount full
atlas --json context ranked status gn-twelve
atlas context ranked gn-twelve
atlas context ranked tree gn-twelve

If the repos moved since the last scan, rerun atlas registry scan before rendering.

For active development sessions, run atlas index start, then use atlas --json index status to inspect freshness. The watcher is polling-based and compares current source snapshots to indexed source snapshots; unchanged repos stay fresh regardless of elapsed time. The same watcher lifecycle keeps git-health cache warm and drains the ranked-context warmer queue, visible under data.tasks.git_health and data.tasks.ranked_contexts. atlas --json context ranked <group>, atlas --json context ranked status <group>, and atlas --json context ranked tree <group> prefer the latest ranked snapshot when one exists; atlas context ranked warm <group> builds that snapshot explicitly when you want a foreground prewarm. Render-only controls such as --portion, --max-tokens, and --max-bytes are then cheap view operations. Ranked preparation does not run dexterity.index; it queries the watcher-maintained index with a bounded timeout and falls back to local lib/ file selection if the query is unavailable. The tree command shows the same ranked repo set as a monorepo-aware file tree, includes source projects even when ranked file selection excluded them for budget/policy reasons, defaults to directories such as lib/, test/, tests/, src/, config/, and priv/, and walks all files under those prefixes unless --max-depth is set.

Fleet and prompt-runner config files are bootstrapped lazily without overwriting user edits:

~/.config/atlas_once/fleet.json
~/.config/atlas_once/prompt_runner.json

Use atlas git status @all --json for cached fleet status and atlas git status @all --refresh --json for a foreground refresh. Prompt runner dry-runs use the same repo selectors and create workflow records without provider side effects:

atlas prompt-run-sdk foo-prompt simulated . --targets atlas_once --dry-run --json
atlas workflow preset list

Real prompt-runner runs should be gated by prompt_runner_sdk packet readiness. The SDK currently exposes the closest readiness surface through:

mix prompt_runner packet preflight <packet-dir>
mix prompt_runner packet doctor <packet-dir>
mix prompt_runner plan <packet-dir>

Atlas persists that SDK preflight result before invoking a provider and fails early when packet-local repos, git state, provider preflight, or CLI confirmation requirements are not ready. Use --preflight-only to record readiness without invoking a provider. Packet setup commands remain explicit; Atlas does not auto-run packet-specific setup scripts from dry-runs.

Repo-local Elixir navigation works after the same install and ranked config setup:

cd ~/p/g/n/claude_agent_sdk
atlas agent status
atlas agent task "add streaming support"
atlas agent find Agent
atlas agent related lib/claude_agent_sdk/agent.ex
atlas index
atlas symbols Agent --limit 10
atlas files lib --limit 20
atlas def ClaudeAgentSDK.Agent
atlas ranked-files --active lib/claude_agent_sdk/agent.ex --limit 10

Atlas runs Dexter and Dexterity through shadow workspaces under ~/.atlas_once/code/shadows, not through .dexter.db in the source repo. atlas agent ... is the short shell-friendly surface for Codex-style use; atlas agent task "<goal>" combines freshness, implementation-first repo structure, bounded backend enrichment, optional impact context, and next commands without long argument lists. Query commands reuse source-snapshot freshness state when available, serialize Dexterity access per shadow, cache successful read-only results against the current shadow index stamp, and filter ranked/impact output to repo-source paths by default. atlas files <pattern> falls back to an implementation-first source scan when Dexterity returns no matches. Agent commands use the persistent intelligence service when it is running, use the backend service query budget by default, and return partial task context when a backend call fails. Use --include-external when stdlib or dependency paths are intentionally needed.

For long sessions, start the optional persistent query service:

atlas intelligence start
atlas intelligence warm .
atlas intelligence status

This starts one Atlas daemon with a bounded lazy Dexterity MCP worker pool. It does not start workers for every configured repo; workers are created only for queried or explicitly warmed shadows, expire after the idle TTL, and are closed/removed if a request times out or errors. Use atlas intelligence warm <ref-or-path>... only for selected active repos.

If the repo-owned template changed in this repo checkout, reimport it into the managed config with:

atlas config ranked install --profile nshkrdotcom --force

If a monorepo layout drifts, prepare now warns and continues. The unmatched override names are preserved in atlas --json context ranked status gn-twelve under unmatched_project_overrides.

If you want to inspect the managed config:

atlas config ranked path
atlas config ranked show

For a simple explicit group, prefer the CLI helper over hand-editing JSON:

atlas config ranked group add my-slice app_kit:gn-ten jido_integration:gn-ten AITrace
atlas config ranked group show my-slice
atlas config ranked group add-repo my-slice AITrace
atlas config ranked group remove-repo my-slice AITrace

Shell Setup

Atlas installs normal commands on PATH. The shell snippet is only for d, because changing directories must happen in the current shell process.

Show the snippet:

atlas config shell show

Install it:

atlas config shell install

Customize Paths

Show effective settings:

atlas config show

Adjust roots and storage:

atlas config set data_home ~/atlas_once
atlas config set code_root ~/code
atlas config roots add ~/code
atlas config roots remove ~/code

List all active roots:

atlas --json config show

The root list is data.settings.project_roots.

Dev Checkout Mode

For local development:

git clone https://github.com/nshkrdotcom/atlas_once
cd atlas_once
uv sync --dev
uv run atlas