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