my-ai-home 0.1.1

Local home base for AI agent skills, MCP servers, profiles, and Claude Code setup

My AI Home

A local control center for Claude Code skills, MCP servers, and project profiles.

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

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:

myai

Install

From PyPI:

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

From source:

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:

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

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:

myai global
myai global doctor
myai global plan --profile coding

Migration:

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

Use --help for generated CLI help:

myai --help
myai plan --help
myai migrate --help

Registry sketch

Skill

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

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

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

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