Metadata-Version: 2.4
Name: my-ai-home
Version: 0.1.0
Summary: Local home base for AI agent skills, MCP servers, profiles, and Claude Code setup
Keywords: claude-code,mcp,skills,tui,workflow
Author: Cookie-HOO
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: textual>=0.86
Requires-Dist: typer>=0.12
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/Cookie-HOO/my-ai-home
Project-URL: Issues, https://github.com/Cookie-HOO/my-ai-home/issues
Project-URL: Repository, https://github.com/Cookie-HOO/my-ai-home
Description-Content-Type: text/markdown

<div align="center">
  <h1>My AI Home</h1>
  <p>A local control center for Claude Code skills, MCP servers, profiles, and project/global setup.</p>
</div>

<p align="center">
  <img alt="Python" src="https://img.shields.io/badge/python-3.11%2B-blue">
  <img alt="Status" src="https://img.shields.io/badge/status-alpha-orange">
  <img alt="License" src="https://img.shields.io/badge/license-MIT-green">
</p>

`my-ai-home` installs the `myai` command. Use it when you keep reusable AI-agent capabilities in a personal `MY_AI_ROOT` workspace and want to install only the relevant skills and MCP servers into each Claude Code project.

It is built for people who maintain many local skills, MCP configs, and project presets, but still want project installs to be explicit, reviewable, and safe.

> [!IMPORTANT]
> The package is currently **alpha**. The registry format is intentionally small and versioned, but command behavior may still evolve.

## Why use it?

- **One home for agent capabilities** — keep skills, MCP definitions, and profiles in a single `MY_AI_ROOT` workspace.
- **Project-scoped installs** — install symlinks into `<project>/.claude/skills/` and MCP entries into `<project>/.mcp.json`.
- **Global scope is explicit** — use `myai global` when you really want to manage Claude Code user/global config.
- **Profiles for repeatable setup** — define curated bundles such as `coding`, then preview or apply them per project.
- **Safe planning flow** — inspect planned changes before writing; unmanaged project-owned entries are not overwritten implicitly.
- **Agent-friendly registries** — YAML registries are the machine source of truth; Markdown manifests remain human documentation.

<details>
<summary>Table of contents</summary>

- [Quickstart](#quickstart)
- [Installation](#installation)
- [Core concepts](#core-concepts)
- [Usage](#usage)
- [Registry format](#registry-format)
- [Safety boundaries](#safety-boundaries)
- [Development](#development)
- [Publishing](#publishing)
- [License](#license)

</details>

## Quickstart

Install the CLI, create or migrate a workspace, then manage a project from that project directory.

```bash
uv tool install my-ai-home

myai migrate --target ~/my_ai
export MY_AI_ROOT=~/my_ai

myai registry check

cd /path/to/project
myai plan --profile coding
myai apply --profile coding
```

Run `myai` with no subcommand in an interactive terminal to open the Textual TUI.

```bash
cd /path/to/project
myai
```

In non-interactive contexts, `myai` prints a project summary instead.

## Installation

### From PyPI

```bash
uv tool install my-ai-home
myai --help
```

### From source

```bash
git clone https://github.com/Cookie-HOO/my-ai-home.git
cd my-ai-home
uv tool install -e .
myai --help
```

### Requirements

- Python `>=3.11`
- [`uv`](https://docs.astral.sh/uv/) for the recommended install and development workflow
- Claude Code if you want the generated `.claude/skills/` and `.mcp.json` project files to be consumed directly

## Core concepts

### `MY_AI_ROOT`

`MY_AI_ROOT` points to your personal AI workflow workspace:

```text
my_ai/
  skills/
    registry.yaml
    custom/
    installed/
    SKILL_MANIFEST.md
  mcps/
    registry.yaml
    MCP_MANIFEST.md
  profiles/
    registry.yaml
  tools/
    TOOL_MANIFEST.md
    EXTERNAL_TOOLS.md
```

Machine-readable sources of truth:

- `skills/registry.yaml`
- `mcps/registry.yaml`
- `profiles/registry.yaml`

Markdown manifest files are for humans and agents. They are not parsed as the machine source of truth.

### Scopes

| Command | Scope | Writes to |
| --- | --- | --- |
| `myai` | Current project | `<project>/.claude/skills/`, `<project>/.mcp.json` |
| `myai migrate` | Bootstrap workspace | Target `MY_AI_ROOT` skeleton and imported file-backed config where safe |
| `myai global` | Claude Code user/global config | Claude Code global/user-scope skills and MCP config |

Project mode refuses to run inside `~/.claude` so global changes are never inferred from the current directory. Use `myai migrate` or `myai global` for that scope.

### Managed vs project-owned entries

`myai` distinguishes entries it manages from entries already owned by a project:

- Managed skill installs are symlinks pointing into `MY_AI_ROOT`.
- Managed MCP installs include `MYAI_*` marker env keys injected by `myai`.
- Existing unmarked MCP entries are treated as project-owned and are not overwritten implicitly.

## Usage

### Open the project TUI

```bash
cd /path/to/project
myai
```

The TUI lets you:

- choose a profile or custom selection,
- toggle skills and MCP servers,
- review the generated plan,
- apply the plan after confirmation.

### Inspect project state

```bash
myai doctor
```

Shows detected skills and MCP servers for the current project, including whether each entry is managed, project-owned, broken, orphaned, or conflicting.

### List available registry entries

```bash
myai list skills
myai list mcps
myai list profiles
```

### Preview and apply a project profile

```bash
myai plan --profile coding
myai apply --profile coding
```

Use `--yes` to apply without an interactive confirmation:

```bash
myai apply --profile coding --yes
```

### Bootstrap or migrate a workspace

```bash
myai migrate --target ~/my_ai --dry-run
myai migrate --target ~/my_ai
export MY_AI_ROOT=~/my_ai
```

`myai migrate` creates a workspace skeleton and imports file-backed global skills or global MCP config where safe. It does **not** delete or mutate old global Claude Code config.

### Validate registries

```bash
myai registry check
```

### Manage global/user scope explicitly

```bash
myai global
myai global doctor
myai global list skills
myai global list mcps
myai global plan --profile coding
```

Global operations are intentionally separate from project operations.

## Command reference

```text
myai [OPTIONS] COMMAND [ARGS]...

Commands:
  doctor    Inspect current project state.
  plan      Preview project changes for a profile.
  apply     Apply project changes for a profile.
  migrate   Create or update a MY_AI_ROOT workspace.
  list      List registry entries.
  registry  Validate registries.
  global    Manage Claude Code global/user scope explicitly.
```

Common options:

| Command | Options |
| --- | --- |
| `myai plan` | `--profile`, `-p` |
| `myai apply` | `--profile`, `-p`, `--yes` |
| `myai migrate` | `--target PATH`, `--dry-run`, `--yes` |

Use `--help` for the full generated help:

```bash
myai --help
myai plan --help
myai migrate --help
myai registry --help
```

## Registry format

All registries are YAML files with `version: 1`.

### Skill registry

```yaml
version: 1
skills:
  readme-writing-polish:
    name: readme-writing-polish
    path: skills/custom/readme-writing-polish
    sourceType: custom
    install:
      type: symlink
    description: README writing and polishing.
    recommendedFor: [coding, docs]
    tags: [readme, writing]
    sensitivity: normal
    status: active
```

Rules:

- The registry key and `name` must match.
- `path` is relative to `MY_AI_ROOT`.
- The target directory must contain `SKILL.md`.
- `sourceType` is `custom` or `installed`.
- `install.type` is currently `symlink`.
- `sensitivity` is one of `normal`, `personal`, `internal`, `secret-adjacent`.
- `status` is one of `active`, `deprecated`, `hidden`.

### MCP registry

```yaml
version: 1
servers:
  fetch:
    name: fetch
    description: Fetch URL content.
    category: [web]
    recommendedFor: [coding, research]
    tags: [fetch, web]
    status: active
    config:
      type: stdio
      command: uvx
      args:
        - mcp-server-fetch
    requires:
      externalTools: [uv]
      env: []
      auth: []
      files: []
    safety:
      network: true
      opensBrowser: false
      writesFiles: false
      externalService: true
      notes: Accesses external network resources.
```

Rules:

- The registry key and `name` must match.
- `config` is copied into project `.mcp.json` when installed.
- Do **not** store tokens, cookies, API keys, passwords, or private env file contents in `mcps/registry.yaml`.
- `MYAI_*` env keys are reserved. Do not write them in registry config; `myai` injects markers only into project installs.

### Profile registry

```yaml
version: 1
profiles:
  coding:
    name: coding
    title: Coding project
    description: Basic Claude Code setup for software projects.
    status: active
    tags: [coding]
    skills:
      required: [brainstorming]
      recommended: [modern-python]
      optional: [readme-writing-polish]
    mcps:
      required: [fetch]
      recommended: []
      optional: [playwright]
```

Rules:

- The registry key and `name` must match.
- `required` and `recommended` are default selections, not hard policy; users can deselect them in the TUI.
- Profile entries reference existing skill and MCP IDs. They do not copy skill contents or MCP config.

## Safety boundaries

`myai` is designed to avoid surprising project/global changes:

- Project mode only writes `.claude/skills/` and `.mcp.json` in the target project.
- Skills are symlinked into projects; skill contents are not copied.
- Existing project-owned MCP entries are not overwritten implicitly.
- MCP registry entries should reference env vars or env files instead of storing secrets.
- `MYAI_*` marker env keys are reserved for `myai` ownership tracking.
- Plugin-provided skills and MCPs remain managed by their plugins.
- `myai migrate` does not delete or mutate old global Claude Code config.
- Global/user-scope changes require explicit `myai global` commands.

## Development

```bash
uv sync --all-groups
uv run myai --help
uv run ruff check .
uv run pytest
uv run ty check src/
uv build
```

The test suite currently covers registry loading, MCP ownership classification, project planning, and project-owned MCP conflict handling.

## Publishing

PyPI Trusted Publishing configuration:

- GitHub repository: `Cookie-HOO/my-ai-home`
- Workflow: `.github/workflows/pypi-publish.yml`
- Environment: `pypi`
- Trigger: GitHub release published, or manual `workflow_dispatch`

The workflow runs lint, tests, type checks, builds the package, then publishes `dist/` with `pypa/gh-action-pypi-publish`.

## License

MIT
