Metadata-Version: 2.4
Name: my-ai-home
Version: 0.1.1
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, and project profiles.</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. It helps you keep reusable AI-agent capabilities in one `MY_AI_ROOT` workspace, then install selected skills and MCP servers into each Claude Code project.

> [!NOTE]
> This project is currently alpha. It is usable, but command behavior and registry details may still change.

## Highlights

- Manage project skills in `<project>/.claude/skills/`.
- Manage project MCP servers in `<project>/.mcp.json`.
- Bootstrap a personal `MY_AI_ROOT` workspace from existing global config.
- Define profiles that bundle common skills and MCPs.
- Preview plans before writing; unmanaged project entries are not overwritten.
- Detect capabilities already visible from parent projects or global config, and avoid reinstalling them locally.
- Keep user/global scope explicit with `myai global`.

## Quickstart

```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 the interactive TUI from a project directory:

```bash
myai
```

## Install

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 .
```

Requirements: Python `>=3.11`; `uv` is recommended.

## Core model

### Workspace

`MY_AI_ROOT` points to your personal AI workflow workspace:

```text
my_ai/
  skills/registry.yaml
  mcps/registry.yaml
  profiles/registry.yaml
```

These YAML registries are the machine source of truth. Markdown manifests are documentation only.

### Scopes

| Command | Scope | Purpose |
| --- | --- | --- |
| `myai` | Current project | Install project skills/MCPs. |
| `myai migrate` | Bootstrap | Create or update a `MY_AI_ROOT` workspace. |
| `myai global` | User/global | Manage Claude Code global-scope config explicitly. |

Project mode refuses to run inside `~/.claude`; use `myai migrate` or `myai global` there.

### Visibility and ownership

Claude Code can see capabilities from the current project, parent project directories, and global/user config. `myai` follows that model:

- current project entries are shown as local state,
- parent project entries are shown as `parent`,
- global/user entries are shown as `global`,
- skills are managed when they are symlinks into `MY_AI_ROOT`,
- MCP entries are managed when they carry `MYAI_*` marker env keys,
- visible parent/global entries satisfy profile requirements and are not reinstalled locally.

## Commands

```bash
myai                         # open TUI, or print summary in non-interactive shells
myai doctor                  # inspect current project state
myai list skills             # list registered skills
myai list mcps               # list registered MCP servers
myai list profiles           # list profiles
myai plan --profile coding   # preview changes
myai apply --profile coding  # apply after confirmation
myai registry check          # validate registries
```

Global scope:

```bash
myai global
myai global doctor
myai global plan --profile coding
```

Migration:

```bash
myai migrate --target ~/my_ai --dry-run
myai migrate --target ~/my_ai
```

Use `--help` for generated CLI help:

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

## Registry sketch

### Skill

```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
```

The path is relative to `MY_AI_ROOT` and must contain `SKILL.md`.

### MCP

```yaml
version: 1
servers:
  fetch:
    name: fetch
    description: Fetch URL content.
    config:
      type: stdio
      command: uvx
      args: [mcp-server-fetch]
    requires:
      externalTools: [uv]
      env: []
      auth: []
      files: []
    safety:
      network: true
      opensBrowser: false
      writesFiles: false
      externalService: true
```

Do not store tokens, cookies, API keys, or private env file contents in MCP registries.

### Profile

```yaml
version: 1
profiles:
  coding:
    name: coding
    title: Coding project
    skills:
      required: [brainstorming]
      recommended: [modern-python]
      optional: [readme-writing-polish]
    mcps:
      required: [fetch]
      recommended: []
      optional: [playwright]
```

`required` and `recommended` are default selections, not hard policy; users can deselect them in the TUI.

## Safety

- Project mode writes only `.claude/skills/` and `.mcp.json` in the target project.
- Skills are symlinked, not copied.
- Existing project-owned MCP entries are not overwritten implicitly.
- Capabilities visible from parent/global scope are not duplicated into the current project by default.
- `myai migrate` does not delete or mutate old global Claude Code config.
- Global changes require explicit `myai global` commands.

## Development

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

## Publishing

Publishing uses PyPI Trusted Publishing:

- Repository: `Cookie-HOO/my-ai-home`
- Workflow: `.github/workflows/pypi-publish.yml`
- Environment: `pypi`
- Trigger: GitHub release or manual workflow dispatch

## License

MIT
