Imported from jeonghwanko/mimi-seed-sdk (AGENTS.md). Install upstream with npx skills add jeonghwanko/mimi-seed-sdk. Copyright stays with the author.

Mimi Seed SDK — Codex contributor guide

This repository is the public developer-tooling source of truth for Mimi Seed. It contains two independently built npm packages: the mimi-seed CLI and the @yoonion/mimi-seed-mcp local stdio MCP server.

Start here

Before non-trivial work, read docs/domain/_index.md. It routes each task to the smallest relevant structural document and records which files are authoritative. Do not load the whole domain folder by default.

Use the following task map after reading the index:

docs/agent-guide.md is for an agent using Mimi Seed tools at runtime. It is not the implementation guide for this repository.

This file and CLAUDE.md (Claude Code) carry the same contract — keep them aligned when either changes.

Repository map and ownership

The private web console is a separate repository with a different transport and auth model. Keep SDK package implementation here; describe only the public boundary to the web console.

Codex integration contracts

• mimi-seed init scaffolds AGENTS.md in a user's project alongside Claude Code context.
• mimi-seed mcp codex --write writes the remote HTTP MCP registration to ~/.codex/config.toml.
• A complete from-source Codex setup installs the repository marketplace/plugin, not only an MCP block, so the user receives both the server and skills/. See docs/from-source.md.
• Plugin or MCP registration changes must keep Codex and Claude Code guidance aligned where their behavior is equivalent, while preserving client-specific instructions where it differs.

Working rules

1. Check git status --short before editing. Preserve unrelated user changes and do not rewrite generated or lock files unless the task requires it.
2. Treat code as the final source of truth. Use the SSOT and drift table in the domain index before updating a mirrored document.
3. Keep changes in the owning package. The two packages are not a workspace and do not import each other. The CLI's src/checks Release Doctor files are generated mirrors of the MCP sources; edit the MCP source, then run npm run release-doctor:sync.
4. Keep register files thin: schemas and MCP handlers live in registers/; business logic lives in the domain's tools.ts or focused module. A new register module is wired into packages/mcp-server/src/server.ts (buildServer), not src/index.ts.
5. Preserve ESM conventions: TypeScript source imports use .js specifiers. Tool names are snake_case, files are kebab-case, and domain directories are lowercase.
6. This is a public repository. Never commit, print, or document secrets, real app/account identifiers, local credential contents, or private console internals. Tests and examples must use obvious placeholders.
7. User-facing onboarding applies to Claude Code and Codex when both support the workflow.

Package-specific rules live in packages/cli/AGENTS.md and packages/mcp-server/AGENTS.md. They apply in addition to this file.

Documentation and generated files

• Do not repeat parameters already defined by a tool schema, or flags already defined by the usage.<command> entries in packages/cli/src/index.ts; link to the owning source instead.
• Never put release version numbers in domain docs. The root package.json and version scripts own them.
• Use “150+” in prose and name domains rather than counting them. Exact tool and domain counts belong only in tool-manifest.json, docs/domain/tool-catalog.md, and the README count columns — docs-drift.test.ts rejects a hard-coded count in any other contributor or agent-facing document.
• Keep English and .ko onboarding documents structurally equivalent when changing user-facing guidance.
• Changes to .codex-plugin/, .mcp.json, skills/, docs/, or LICENSE require npm run plugin:sync. Commit the resulting plugins/mimi-seed/ update; do not hand-edit it.
• Do not hand-edit the CLI Release Doctor mirror. npm run release-doctor:check enforces byte equality with the MCP-owned source and npm run release-doctor:sync refreshes it.

Verification

Run the narrowest relevant checks first, then the owning package's full checks:

# CLI change
npm run build --prefix packages/cli
npm test --prefix packages/cli

# MCP server change
npm run build --prefix packages/mcp-server
npm test --prefix packages/mcp-server

# Plugin, skills, copied docs, manifests, or release metadata
npm run plugin:check

# Cross-package or release-ready verification
npm test

The root npm test checks Codex plugin drift and runs both package test suites. The root npm run build is a bootstrap operation that installs and builds both packages; prefer package-scoped builds during normal edits.

packages/cli builds with tsup, which does not type-check; its npm test therefore runs npm run typecheck (tsc --noEmit) before vitest, and you can run that step alone while iterating. To run a single test file: npx vitest run src/__tests__/<file>.test.ts from inside the package. Test names and failure messages are Korean and usually name the fix; docs/domain/testing.md maps every guard to the fact it protects.