@joehom/awm-cli 0.0.1

package/README.md

@@ -0,0 +1,666 @@
+# AWM — Agent Workspace Manager
+
+A local-first CLI for managing MCP servers and skills across AI coding tools.
+
+AWM keeps a **central registry** of MCPs and skills in `~/.agent-workspace/registry/`. Each project has a `.awm.json` file that declares which tools, MCPs, and skills it uses. Running `awm mcp add` or `awm skill add` updates `.awm.json` and immediately writes the right config files for every listed tool.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [Quick Start](#quick-start)
+- [Workspace Commands](#workspace-commands)
+- [MCP Commands](#mcp-commands)
+- [Skill Commands](#skill-commands)
+- [Tool Command](#tool-command)
+- [Doctor Command](#doctor-command)
+- [Setup Command](#setup-command)
+- [Pull Command](#pull-command)
+- [Workspace Config (.awm.json)](#workspace-config-awmjson)
+- [Registry Layout](#registry-layout)
+- [MCP Definition Format](#mcp-definition-format)
+- [Supported Tools](#supported-tools)
+- [Environment Variables](#environment-variables)
+- [Adding a Custom Tool](#adding-a-custom-tool)
+
+---
+
+## Installation
+
+**Requirements:** Node.js 18 or later.
+
+```bash
+# Clone and install dependencies
+git clone <repo-url>
+cd nano-ai-workspace-manager
+npm install
+
+# Use directly
+node bin/awm.js --help
+
+# Or install globally
+npm install -g .
+awm --help
+```
+
+On install, default MCPs (`github`, `filesystem`, `memory`, `fetch`) and the `awm-cli` skill are seeded into the registry automatically.
+
+---
+
+## Core Concepts
+
+| Concept | What it is |
+|---------|-----------|
+| **MCP** | A Model Context Protocol server definition stored in the global registry. Describes how to launch a server (command, args, env vars). |
+| **Skill** | A folder of instruction files for an AI tool. The registry stores the canonical copy; `skill add` copies it into your project. |
+| **Workspace** | A `.awm.json` file at your project root listing which tools, MCPs, and skills are active for that project. |
+| **Tool** | A JSON definition that tells AWM where each AI tool stores its MCP config and skill folder. |
+
+The registry is the single source of truth. Tool config files (`.mcp.json`, `.cursor/mcp.json`, etc.) are **generated output** — AWM regenerates them whenever you add or remove MCPs/skills.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Go to your project
+cd /path/to/your/project
+
+# 2. Initialise workspace — pick which tools to support
+awm init
+
+# 3. Add MCPs (checkbox list, auto-applied to all tools)
+awm mcp add
+
+# 4. Add skills (checkbox list, auto-applied to all tools)
+awm skill add
+
+# 5. Check the workspace state
+awm status
+
+# 6. Validate everything is healthy
+awm doctor
+```
+
+---
+
+## Workspace Commands
+
+### `awm init [--force]`
+
+Create a `.awm.json` in the current directory. Presents a checkbox list of all known tools — select the ones your project uses.
+
+```bash
+awm init
+```
+
+```
+? Select tools to support in this workspace: (Press <space> to select)
+❯◯ claude-code
+ ◯ codex
+ ◯ cursor
+ ◯ gemini-cli
+ ◯ github-copilot
+ ◯ windsurf
+
+[ok] Workspace initialized with tools: claude-code, cursor
+     Run "awm mcp add" to add MCPs, "awm skill add" to add skills.
+```
+
+Use `--force` to overwrite an existing `.awm.json`.
+
+---
+
+### `awm status`
+
+Show the current workspace state from `.awm.json`.
+
+```bash
+awm status
+```
+
+```
+Workspace status:
+  Tools:    claude-code, cursor
+  MCPs:     fetch, memory
+  Skills:   awm-cli
+  lastSync: 2026-03-08T12:00:00Z
+```
+
+---
+
+## MCP Commands
+
+MCP definitions are stored as JSON files at `~/.agent-workspace/registry/mcps/<id>.json`.
+
+### `awm mcp register [id]`
+
+Interactively register an MCP server into the global registry. Supply `[id]` to skip the ID prompt.
+
+```bash
+awm mcp register
+awm mcp register github
+```
+
+| Prompt | Description |
+|--------|-------------|
+| MCP ID | Unique slug, e.g. `github`, `postgres-dev` |
+| Transport | `stdio` · `sse` · `http` |
+| Command | Executable to run, e.g. `npx`, `node`, `uvx` |
+| Args | Space-separated arguments |
+| Env vars | Space-separated `KEY=VALUE` pairs |
+
+```
+? MCP ID (unique slug): github
+? Transport: stdio
+? Command: npx
+? Args: -y @modelcontextprotocol/server-github
+? Env vars: GITHUB_PERSONAL_ACCESS_TOKEN=${env:GITHUB_TOKEN}
+[ok] MCP "github" registered in global registry
+```
+
+---
+
+### `awm mcp unregister <id>`
+
+Remove an MCP from the global registry. Does not affect `.awm.json` or any config files already written.
+
+```bash
+awm mcp unregister github
+```
+
+---
+
+### `awm mcp import`
+
+Scan the current directory for existing tool config files and register any MCP entries found into the global registry. Skips MCPs already in the registry.
+
+Files scanned:
+
+| File | Tool |
+|------|------|
+| `.mcp.json` | Claude Code |
+| `.cursor/mcp.json` | Cursor |
+| `.gemini/settings.json` | Gemini CLI |
+| `.vscode/mcp.json` | GitHub Copilot |
+| `~/.copilot/mcp-config.json` | Copilot CLI |
+| `~/.codeium/windsurf/mcp_config.json` | Windsurf |
+
+```bash
+awm mcp import
+```
+
+```
+[ok] Registered "fetch" from .mcp.json
+     Skipping "memory" (already in registry)
+     Import complete: 1 registered, 1 skipped.
+```
+
+---
+
+### `awm mcp add [--dry-run]`
+
+Select MCPs from the global registry to add to this workspace. After selection, AWM writes them to every tool config file listed in `.awm.json`.
+
+Press **ESC** or **Ctrl+C** to cancel without making changes.
+
+```bash
+awm mcp add
+```
+
+```
+? Select MCPs to add to this workspace: (Press <space> to select)
+❯◯ fetch
+ ◯ memory
+ ◯ github
+
+[ok] Wrote 2 MCP(s) to .mcp.json
+[ok] Wrote 2 MCP(s) to .cursor/mcp.json
+[ok] Added MCPs: fetch, memory
+```
+
+Use `--dry-run` to preview what would be written without touching any files.
+
+---
+
+### `awm mcp delete [--dry-run]`
+
+Select MCPs to remove from this workspace. AWM re-applies the remaining MCPs to all tool config files (overwriting the MCP section).
+
+Press **ESC** or **Ctrl+C** to cancel.
+
+```bash
+awm mcp delete
+```
+
+```
+? Select MCPs to remove from this workspace: (Press <space> to select)
+❯◉ fetch
+ ◯ memory
+
+[ok] Wrote 1 MCP(s) to .mcp.json
+[ok] Removed MCPs: fetch
+```
+
+---
+
+### `awm mcp list [-g]`
+
+List MCPs in the current workspace. Add `-g` / `--global` to list the global registry instead.
+
+```bash
+awm mcp list        # workspace MCPs
+awm mcp list -g     # all registry MCPs
+```
+
+```
+Workspace MCPs:
+  fetch
+  memory
+```
+
+---
+
+### `awm mcp show <id>`
+
+Print the full stored definition for an MCP.
+
+```bash
+awm mcp show github
+```
+
+```json
+{
+  "id": "github",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
+  }
+}
+```
+
+---
+
+## Skill Commands
+
+Skills are stored as directories at `~/.agent-workspace/registry/skills/<name>/`. Each must contain a `SKILL.md` file.
+
+### `awm skill register <name> --from <path>`
+
+Register a skill from a local directory or a single `.md` file into the global registry.
+
+```bash
+# From a directory (must contain SKILL.md)
+awm skill register clean-arch --from ./my-skills/clean-arch/
+
+# From a single markdown file
+awm skill register tdd-guide --from ./tdd.md
+```
+
+```
+[ok] Skill "clean-arch" registered in global registry
+```
+
+---
+
+### `awm skill unregister <name>`
+
+Remove a skill from the global registry. Does not delete copies already written into projects.
+
+```bash
+awm skill unregister tdd-guide
+```
+
+---
+
+### `awm skill import`
+
+Scan the current directory for skill folders and register any found into the global registry. Directories scanned: `.claude/skills/`, `.agents/skills/`.
+
+```bash
+awm skill import
+```
+
+```
+[ok] Registered "clean-arch" from .claude/skills
+     Skipping "awm-cli" (already in registry)
+     Import complete: 1 registered, 1 skipped.
+```
+
+---
+
+### `awm skill add [--dry-run]`
+
+Select skills from the global registry to add to this workspace. After selection, AWM copies them into every tool's skill directory listed in `.awm.json` (only tools that support skills, e.g. `claude-code`).
+
+Press **ESC** or **Ctrl+C** to cancel.
+
+```bash
+awm skill add
+```
+
+```
+? Select skills to add to this workspace: (Press <space> to select)
+❯◯ awm-cli
+ ◯ clean-arch
+
+[ok] Copied skill "awm-cli" → .claude/skills/awm-cli
+[ok] Added skills: awm-cli
+```
+
+---
+
+### `awm skill delete`
+
+Select skills to remove from this workspace. Updates `.awm.json` only — does not delete files from tool directories.
+
+Press **ESC** or **Ctrl+C** to cancel.
+
+```bash
+awm skill delete
+```
+
+---
+
+### `awm skill list [-g]`
+
+List skills in the current workspace. Add `-g` / `--global` to list the global registry instead.
+
+```bash
+awm skill list      # workspace skills
+awm skill list -g   # all registry skills
+```
+
+---
+
+### `awm skill show <name>`
+
+Print the `SKILL.md` content for a skill.
+
+```bash
+awm skill show awm-cli
+```
+
+---
+
+## Tool Command
+
+### `awm tool`
+
+Open an interactive checkbox list of all known tools. Tools already selected for this workspace are pre-checked. Confirm to save the new tool list to `.awm.json` and resync all MCPs and skills to every selected tool.
+
+Press **ESC** or **Ctrl+C** to cancel without changes.
+
+```bash
+awm tool
+```
+
+```
+? Select tools for this workspace (space to toggle, enter to confirm):
+❯◉ claude-code
+ ◯ codex
+ ◉ cursor
+ ◯ gemini-cli
+ ◯ github-copilot
+ ◯ windsurf
+
+Resyncing MCPs and skills to updated tool list...
+[ok] Tools updated: claude-code, cursor
+```
+
+---
+
+## Doctor Command
+
+### `awm doctor`
+
+Validate the registry and current workspace for consistency. Checks:
+
+- Registry directories exist
+- Every MCP JSON file in the registry is valid (`id`, `transport`, `command`)
+- Every tool definition is structurally valid
+- If `.awm.json` exists in the current directory:
+  - Valid JSON with `tools`, `mcps`, `skills` arrays
+  - All tool IDs are known
+  - All MCP IDs exist in the registry
+  - All skill names exist in the registry with a `SKILL.md`
+
+```bash
+awm doctor
+```
+
+**Clean output:**
+
+```
+[ok] No issues found
+```
+
+**Output when issues exist (exit code 1):**
+
+```
+[error] .awm.json: MCP "old-server" not found in registry
+[error] .awm.json: skill "missing-skill" not found in registry
+[error] MCP file "broken.json": MCP requires a string "command" field
+```
+
+Run `doctor` after manual registry edits or before sharing a project.
+
+---
+
+## Setup Command
+
+### `awm setup [--force]`
+
+Re-seed the registry with the default MCPs, skills, and tool definitions bundled with AWM. Already-present entries are skipped unless `--force` is passed.
+
+```bash
+awm setup           # skips existing entries
+awm setup --force   # overwrites with fresh defaults
+```
+
+**Default MCPs seeded:**
+
+| ID | Command | Notes |
+|----|---------|-------|
+| `github` | `npx -y @modelcontextprotocol/server-github` | Needs `GITHUB_TOKEN` env var |
+| `filesystem` | `npx -y @modelcontextprotocol/server-filesystem` | Local file access |
+| `memory` | `npx -y @modelcontextprotocol/server-memory` | Persistent knowledge graph |
+| `fetch` | `uvx mcp-server-fetch` | Web fetching (requires `uv`) |
+
+---
+
+## Pull Command
+
+### `awm pull [type] [--tool <id>] [--force] [--dry-run]`
+
+Read each AI tool's **global config files** and register any MCPs or skills found there into the global AWM registry. This is the fastest way to populate the registry from tools you already have configured (e.g. MCPs in `~/.claude.json`, skills in `~/.claude/skills/`).
+
+After pulling, use `awm mcp add` / `awm skill add` to activate entries in a workspace.
+
+```bash
+awm pull              # pull both skills and MCPs from all tools
+awm pull skills       # pull skills only
+awm pull mcps         # pull MCPs only
+awm pull --tool claude-code   # scope to one tool
+awm pull --force              # overwrite existing registry entries
+awm pull --dry-run            # preview without making changes
+```
+
+**Example — dry-run across all tools:**
+
+```
+[dry-run] Would register MCP "pencil" from claude-code
+[dry-run] Would register skill "clean-arch" from claude-code
+  [skill] Skipping "awm-cli" (already registered)
+[dry-run] Would register MCP "pencil" from codex
+MCPs: 2 pulled, 1 skipped | Skills: 1 pulled, 1 skipped
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `[type]` | `skills` or `mcps`. Omit to pull both. |
+| `--tool <id>` | Limit to a single tool ID (e.g. `claude-code`, `cursor`). |
+| `--force` | Overwrite entries that already exist in the registry. |
+| `--dry-run` | Show what would be imported without writing anything. |
+
+**What gets scanned:**
+
+| Tool | Global MCP file | Global skills folder |
+|------|----------------|---------------------|
+| `claude-code` | `~/.claude.json` | `~/.claude/skills/` |
+| `codex` | `~/.codex/config.toml` | `~/.agents/skills/` |
+| `cursor` | `~/.cursor/mcp.json` | `~/.cursor/rules/` |
+| `gemini-cli` | global settings file | global skills folder |
+| `windsurf` | global MCP config | — |
+| `copilot-cli` | global MCP config | — |
+| `github-copilot` | — (no global MCP) | — |
+
+Skills must be directories containing a `SKILL.md` file to be picked up. MCP entries without a `command` field are skipped.
+
+---
+
+## Workspace Config (.awm.json)
+
+Created by `awm init` at the project root. Managed automatically by AWM — you can also edit it manually and run `awm doctor` to validate.
+
+```json
+{
+  "tools": ["claude-code", "cursor"],
+  "mcps": ["fetch", "memory"],
+  "skills": ["awm-cli"],
+  "lastSync": "2026-03-08T12:00:00Z"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `tools` | AI tools to write configs for in this project |
+| `mcps` | MCP IDs from the global registry active in this project |
+| `skills` | Skill names from the global registry active in this project |
+| `lastSync` | Timestamp of the last apply (set automatically) |
+
+---
+
+## Registry Layout
+
+```
+~/.agent-workspace/
+  registry/
+    mcps/
+      github.json
+      fetch.json
+      memory.json
+
+    skills/
+      awm-cli/
+        SKILL.md
+      clean-arch/
+        SKILL.md
+
+    tools/              ← user overrides (optional)
+      my-custom-tool.json
+```
+
+The built-in tool definitions are bundled with the CLI. The `tools/` directory in the registry is for **user-defined overrides** — AWM checks it first.
+
+---
+
+## MCP Definition Format
+
+```json
+{
+  "id": "my-server",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "env": {
+    "MY_TOKEN": "${env:MY_TOKEN}"
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | Yes | Unique registry slug. Used as the key in generated config files. |
+| `transport` | Yes | `stdio`, `sse`, or `http` |
+| `command` | Yes | Executable to run |
+| `args` | No | Array of arguments |
+| `env` | No | Env vars to pass. `${env:VAR}` values are written verbatim — the target tool resolves them at runtime. |
+
+---
+
+## Supported Tools
+
+| Tool ID | Name | MCP format | Skills | Project MCP file |
+|---------|------|-----------|--------|-----------------|
+| `claude-code` | Claude Code | JSON | Yes | `.mcp.json` |
+| `codex` | Codex | TOML | No | `.codex/config.toml` |
+| `cursor` | Cursor | JSON | No | `.cursor/mcp.json` |
+| `gemini-cli` | Gemini CLI | JSON | No | `.gemini/settings.json` |
+| `github-copilot` | GitHub Copilot | JSON | No | `.vscode/mcp.json` |
+| `windsurf` | Windsurf | JSON | No | — (global only) |
+| `copilot-cli` | Copilot CLI | JSON | No | — (global only) |
+
+Notes:
+- **claude-code** is the only tool that supports skills.
+- **windsurf** and **copilot-cli** are global-scope only; workspace apply skips them for project-scoped config files.
+- **github-copilot** uses `servers` as the root key (not `mcpServers`).
+- **codex** uses TOML with `mcp_servers` as the root key.
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AWM_REGISTRY` | `~/.agent-workspace/registry` | Override the registry root. Useful for testing or team shared registries. |
+
+```bash
+# Isolated registry for testing
+AWM_REGISTRY=./test-registry awm mcp list -g
+
+# Shared team registry
+AWM_REGISTRY=/mnt/shared/awm-registry awm mcp list -g
+```
+
+---
+
+## Adding a Custom Tool
+
+Create a JSON file in `~/.agent-workspace/registry/tools/` named `<id>.json`. AWM will use it in place of any built-in definition with the same ID, or add it as a new tool.
+
+**Example: `~/.agent-workspace/registry/tools/my-tool.json`**
+
+```json
+{
+  "id": "my-tool",
+  "name": "My Custom AI Tool",
+  "supports": {
+    "mcp": true,
+    "skills": false
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".my-tool/mcp.json",
+      "rootObject": "mcpServers"
+    }
+  }
+}
+```
+
+After saving, the tool is immediately available:
+
+```bash
+awm tool          # my-tool appears in the checkbox list
+```
+
+**Supported MCP formats:**
+- `"format": "json"` — writes a JSON file
+- `"format": "toml"` — writes a TOML file (e.g. like Codex)

package/bin/awm.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js';

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@joehom/awm-cli",
+  "version": "0.0.1",
+  "description": "Agent Workspace Manager CLI — manages MCP servers, skills, and profiles for AI coding tools",
+  "type": "module",
+  "bin": {
+    "awm": "bin/awm.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "postinstall": "node src/seed.js"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^10.2.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "",
+  "repository": "",
+  "homepage": ""
+}