@hasna/configs

AI coding agent configuration manager — store, version, apply, and share all your AI coding configs. CLI + MCP + REST API + Dashboard.

Install

npm install -g @hasna/configs

CLI Usage

configs --help
configs list                    # compact, paged summary
configs list --verbose          # expanded metadata, still paged
configs list --json             # full machine-readable records
configs show <slug>             # full metadata + content
configs inspect <slug>          # alias for show
configs profile resolve
configs profile apply --auto

Collection commands are compact by default to keep agent terminals and context small. Human output is capped at 20 rows unless you pass --limit; use --cursor to continue from the next page. Detail is explicit:

• --verbose expands list rows with descriptions, tags, and paths.
• --json preserves full machine-readable records for automation.
• show/inspect and snapshot show print full config or snapshot content.

MCP Server

configs-mcp

Agent-facing MCP tools follow the same gradual disclosure model. list_configs and list_profiles return paged compact envelopes by default and accept limit, cursor, and verbose. apply_config and apply_profile omit previous_content and new_content unless verbose: true is passed. Use get_config when full config content is needed.

HTTP mode

configs-mcp --http               # http://127.0.0.1:8807/mcp
MCP_HTTP=1 configs-mcp

Health: GET http://127.0.0.1:8807/health. MCP is also mounted on configs-serve at /mcp.

REST API

configs-serve

Storage Sync

This package supports optional remote storage sync through a package-local Postgres connection:

export HASNA_CONFIGS_DATABASE_URL=postgres://...
configs storage status
configs storage push
configs storage pull
configs storage sync

The MCP server also exposes storage_status, storage_push, storage_pull, and storage_sync.

Data Directory

Data is stored in ~/.hasna/configs/.

Session Instruction Rendering

configs session plan and configs session apply render OpenIdentities and OpenConfigs instruction sources into provider-native files for Claude, Codex, Cursor, OpenCode, and Codewith.

configs session plan \
  --tool codewith \
  --profile account999 \
  --identity-export ./instructions.json \
  --source project:repo-rules=./CODEWITH.md \
  --json

configs session apply \
  --tool codex \
  --profile account999 \
  --identity-export ./instructions.json

Accepted source layers are global, provider/tool, account, identity/agent, project, and local. Empty renders fail closed unless --allow-empty-sources is passed. Apply writes generated manifests with file hashes, checks previous manifests for drift, refuses unmanaged file conflicts unless --force is passed, removes stale managed mirrors only when safe, and writes local snapshots before mutating managed files.

Machine-aware Profiles

configs init now seeds two platform profiles:

• linux-arm64 for linux-node-a / linux-node-b
• macos-arm64 for macos-node-a / macos-node-b

These profiles resolve machine variables like {{WORKSPACE_ROOT}}, {{BUN_BIN_DIR}}, {{BUN_PATH}}, and {{PATH_PREFIX}}, so synced configs can be portable across Linux and macOS arm64 machines.

They also include project dashboard variables used by agent-managed project workflows:

• {{PROJECT_DASHBOARD_DIR}} -> .hasna/project
• {{PROJECT_DASHBOARD_RENDER_MANIFEST}} -> .hasna/project/dashboard/render.json
• {{PROJECT_DASHBOARD_SNAPSHOTS_DIR}} -> .hasna/project/dashboard/snapshots
• {{PROJECT_CHANNEL_PREFIX}} -> iproj-

configs init and bun run seed seed the agent-managed-project-dashboard-standard reference. It documents the standard .hasna/project layout, projects dashboard * commands, provider panel commands, #iproj-* channel naming, durable todos/goal workflow, and the rule that dashboards must show ids/statuses/evidence refs instead of raw private documents or secrets.

License

Apache-2.0 -- see LICENSE