AIShell

A macOS-native MCP runtime that gives AI development hosts fresh workspace state, bounded context, and retained execution evidence—without collapsing every operation into a shell string.

日本語

Built and maintained by Quo at kitepon.dev.

Ownership boundary: this repository owns the standalone macOS Apple Silicon runtime, including installation, configuration, state/schema migration, diagnostics, recovery, updates, and releases. dotagents consumes the public contract for cross-product wiring and compatibility; it does not control AIShell's internal operation.

AIShell owns the OS-facing state below the model: file identity, filesystem reconciliation, directly launched processes, complete logs, and retained artifacts. The AI host remains responsible for reasoning, threads, compaction, sub-agents, and general-purpose terminal work.

Try it in 30 seconds

Requires an Apple Silicon Mac running macOS 15 or later.

npm install -g @quolu/aishell && aishell-setup

フォルダの事前登録は不要です。新しいCodex taskで対象フォルダを指定して実行します。

Use workspace_snapshot for the initial workspace context. Run the focused tests with
run_check, and read retained output with artifact_read only if the summary omits evidence.

The default profile exposes five high-density development tools, runtime status, and the retired manager entrypoint:

Tool	Purpose
workspace_snapshot	Bounded initial workspace preview, reconciled change delta, Git state, and primary context
read_context	Budgeted multi-file reads with SHA-256 identity and continuation
search_context	Budgeted lexical context from a directly launched rg worker, scoped to a directory or one regular file; the expanded capability also provides cursor-bound semantic definition/reference/symbol queries without lexical fallback
run_check	Direct process execution, primary diagnostics, and complete stdout/stderr artifacts
artifact_read	Range, tail, and pattern-centered reads from retained artifacts; the expanded capability also searches and compares finalized managed-run artifacts
runtime_status	実行状態と相対パスの基準
runtime_open_manager	互換用の旧入口。管理UIの廃止をMANAGER_REMOVEDで返す

Set AISHELL_CAPABILITY_SET=expanded-v1 on the MCP server process to opt in to the candidate surface. It exposes nine high-density development tools, runtime status, and the retired manager entrypoint. The added tools are run_observe, workspace_wait, change_impact, and apply_change_set; existing tools gain closed managed-run, artifact query, semantic search, project-profile, and Git branch/worktree modes. Cross-run artifact operations require an explicit project path and reject live, expired, legacy-unbound, or different-project evidence instead of silently falling back to partial logs.

For Codex, register the expanded surface explicitly:

aishell-setup --ai codex

Unknown or empty AISHELL_CAPABILITY_SET and AISHELL_TOOL_PROFILE values fail startup with typed errors; they never fall back to another profile.

For lexical search_context, omitting ranking is valid: requests without a workspace cursor prioritize tests, while requests with changed_since_cursor prioritize changed paths and tests. Explicit changed ranking still requires that cursor.

AISHELL_TOOL_PROFILE=factory is a separate, one-tool surface for factory reporters rather than development work. It exposes only factory_diagnostics, a path- and activity-free native readiness report.

調査対象を絞って読む

通常のsnapshot再取得は、稼働中の変更観測と前回の全件照合以降の通知が連続する場合に、保持した一覧へ実ファイルの差分を反映する（checkpointState: "reconciled"）。通知欠落・保持範囲超過・観測停止時は全件を再構築する。restart時はcheckpointとfilesystemを照合し、未変更の内容hashを再利用する。entry_limitとcontext_budgetは返却量だけを制限し、観測範囲を狭めない。

workspace_snapshotのcontext_pathsに注目するファイルを指定すると、その本文を共有予算内で抜粋する。 省略時は案内・構成・実装を優先して最大8件を選び、隠し管理ファイルとarchiveは既定の本文候補から外す。 ファイル一覧や明示読取りは維持する。調査意図を推測する機能は持たない。

{"path":"/absolute/repo","context_paths":["bin/setup-windows-native-factory.ps1","bin/agents-update.sh"],"context_budget":6500}

read_contextは予算を指定対象へ配り、小さい対象の余りを再配分する。各抜粋はSHA、行番号、byte位置、 残りの未読byte数を持つ。続きは同じtargetsと返却されたcontinuationで読み、対象が変わった場合は CONTENT_CHANGEDで止まる。従来のパス文字列に加え、行範囲と期待SHAを指定できる。

{"targets":["/absolute/repo/PLAN.md",{"path":"/absolute/repo/bin/agents-update.sh","start_line":80,"end_line":110}],"byte_budget":15000}

検索はqueriesにbefore_lines・after_linesを付けると、周辺コードを本文に返す。 明示したrankingを保ち、同じ優先度のquery・ファイルを交互に表示する。一致が多い広いregexでは、 欲しい実装が最初のページに入る保証はない。異なる関心はqueryを分けると見渡しやすい。 返却されたpath・行番号をread_contextへ渡せば、必要な範囲を広げられる。

上限、未返却件数、continuation、SHA/cursorは維持する。readのreturnedBytesは本文byte数、検索は 一致・周辺コードrecordのbyte数を表し、MCP envelope全体の大きさではない。単一recordが検索予算を 超える場合は明示descriptorとartifactへ分ける。完全証拠は返却期限まで保持する。 本文はMCPのcontentに一度だけ置き、structuredContentは位置・SHA・cursor等を保持する。

Why AIShell

Typical stateless integrations repeatedly ask the model to rediscover workspace state and interpret command output. AIShell keeps the stateful, OS-facing part below the model so later turns can ask for deltas and primary evidence instead of rescanning everything.

Concern	AIShell	Typical shell-first integration
Workspace state	File identity plus filesystem observation and reconciliation	Re-run commands and reconstruct state from text
Context	Bounded, cursor-based structured results	Unbounded or manually truncated stdout
Execution	Executable URL, arguments, working directory, and lifecycle remain separate	A shell evaluates one command string
Evidence	Complete stdout/stderr retained behind expiring handles	Evidence often disappears when the response is truncated
Scope	macOS access permissions	Depends on the surrounding shell and host policy

AIShell is not a sandbox and does not make arbitrary code execution safe. Its process rails exist to preserve typed execution and observable lifecycle—not to stop renamed binaries or child processes launched by an allowed worker.

Architecture

flowchart LR
    Host[AI host<br/>reasoning · threads · compaction] --> MCP[AIShellMCP<br/>MCP 2025-11-25]
    MCP --> Core[AIShellCore]
    Core --> State[File identity<br/>FSEvents + reconciliation]
    Core --> Process[Direct process lifecycle<br/>stdout · stderr · timeout]
    Core --> Evidence[Retained evidence<br/>artifacts · freshness]
    Process --> Workers[git · rg · compiler · tests]
    State --> macOS[macOS APIs]
    Evidence --> Host

Loading

AIShellCore owns domain behavior. AIShellMCP only translates protocol requests and results. Git, ripgrep, compilers, tests, and SourceKit-LSP remain directly launched workers rather than becoming new state owners.

Install from npm

global packageはaishell-mcp、aishell-setupをPATHへ追加する。npm install自体ではスクリプトも管理アプリも起動しない。

対象AIのCLI（claude、codex、grok、Cursorのagent）を先に導入する。setupは各CLIからの読戻しも確認する。

aishell-setupは導入済みのClaude Code・Codex・Grok Build・Cursorを検出し、MCP登録、設定の読戻し、実際のMCP操作まで確認する。登録はbare aishell-mcp＋AISHELL_CAPABILITY_SET=expanded-v1。利用者のenv、PATH、他の設定を保持する。--aiで対象を指定でき、--checkは設定を変更せず診断する。Windows/LinuxとIntel Macは対象外。詳細は製品単体の導入契約を参照。

更新後も同じaishell-setupを実行する。登録保持・読戻し・MCP実操作まで確認する。管理UIとKeychain認証は不要。接続済みのMCPは、hostで再接続すると新版へ切り替わる。

npm install -g @quolu/aishell && aishell-setup

The current experimental build is not yet Developer ID signed or notarized.

Build from source

git clone https://github.com/kitepon/aishell.git
cd aishell
swift test
npm run build:npm

実行ファイルはdist/aishell-mcpとdist/aishell-run-supervisorへ生成する。

フォルダ登録は不要です。絶対パスは指定した場所を、相対パスと省略時はMCP起動ディレクトリを基準にします。Git worktreeも直接指定できます。旧設定の許可フォルダ一覧は無視されます。

Connect another AI host

For a global npm installation, register the executable name from PATH and the expanded development surface:

aishell-setup --ai claude,codex,grok,cursor
aishell-setup --check

Remove the registration with:

codex mcp remove aishell

Without the expanded capability, the compatibility profile retains all 25 tools. The default seven are the five development tools plus runtime status and the retired manager entrypoint; full mode adds the remaining legacy primitives. With expanded-v1, development exposes 11 tools and full exposes 29:

AISHELL_TOOL_PROFILE=full /opt/homebrew/bin/aishell-mcp
AISHELL_CAPABILITY_SET=expanded-v1 AISHELL_TOOL_PROFILE=full /opt/homebrew/bin/aishell-mcp

The full profile includes file listing and reads, atomic SHA-256-guarded updates, copy/move/rename/Trash, direct process execution, app discovery and launch, runtime status.

apply_change_setは編集状態を通常のJSONとして保存し、新しい暗号鍵や所有者証明を作らない。競合検出、差分、再起動後の継続を維持する。 ローカル鍵を使っていた旧版の記録は必要になった時に読み取り、通常の編集で更新する記録から平文へ切り替える。旧鍵や履歴の一括削除は行わない。 使用ログは~/Library/Application Support/AIShell/activity.jsonlへ保存する。詳しくは導入契約を参照。

Execution and safety boundaries

• AIShell never evaluates a shell command string. It resolves a development program from PATH to an executable URL and keeps arguments, environment, and working directory separate.
• Direct launch of shell and wrapper basenames such as sh, bash, zsh, env, and osascript is rejected as a product rail, not advertised as a security boundary.
• run_check is an open-world capability: an allowed worker may update files, launch child processes, or access the network. AI hosts may require approval before execution.
• npm projects may opt a build, test, or lint check into freshness caching with the closed direct-Node package.json declaration documented in docs/adr/0009-project-profile-contract.md. Ordinary npm scripts remain executable but cache-ineligible; AIShell does not infer arguments, inputs, or effects from shell script text.
• Text updates may use SHA-256 or expected old text as a precondition. Deletes go to Trash.
• 管理UIと停止設定は廃止した。旧runtime.jsonは操作の条件にしない。

Current limitations

• stdio requestは復旧操作・読み取り・実行の3系統で処理する。読み取りと復旧操作は長時間の実行中も応答するが、実行系requestは直列化する。
• MCPのnotifications/cancelledを受け付ける。管理対象processの明示的な停止はrun_observeのcancelで行う。
• A timeout terminates the directly owned process tree, but an allowed worker remains capable of open-world side effects before termination.
• Initial workspace entries are a bounded preview; later deltas are cursor-paged.
• Developer ID signing and notarization are not yet configured.

Operations, updates, and releases

Upgrade a standalone installation through the same official npm path used for initial installation, then run the explicit setup:

npm install -g @quolu/aishell@latest && aishell-setup

runtime_statusで実行状態を確認できる。管理UIは廃止済み。 Factory consumers call factory_diagnostics through the dedicated AISHELL_TOOL_PROFILE=factory MCP surface; its schema and privacy boundary are owned by the product contract.

公開はGitHub Actionsの公開workflowから行う。 AIShellProduct.versionとpackage.jsonの版を揃え、docs/archive/releases/へrelease notesを追加し、変更をmainへ反映する。 そのcommitに対応する版タグを送ると、配布物の検査、npmへの直接公開、GitHub Release作成まで自動で進む。

git tag "v$(node -p 'require("./package.json").version')"
git push origin "v$(node -p 'require("./package.json").version')"

npmにはkitepon/aishellのpublish.ymlをTrusted Publisherとして登録し、npm publishを許可する。 公開jobはGitHub管理のMacで動き、OIDCで自動認証する。長期npm tokenと公開ごとのTouch IDは不要。 通常CIの別runを待つgateは持たず、既定ブランチへの反映と配布物を公開job自身が確認する。 prepublishOnlyを明示実行してから公開するため、lifecycleによる同じビルドの再実行も行わない。

公開後は標準の更新入口で導入する。

npm install -g @quolu/aishell@latest && aishell-setup

aishell-setup --checkと工場診断で導入結果を確認する。既存MCPは再接続または新しいセッションで新版へ切り替わる。 初回のTrusted Publisher設定変更時にnpmが要求する本人認証は別途必要になる。

Development

swift test
npm run build:npm

実装はSources/AIShellCore、Sources/AIShellMCP、Sources/AIShellRunSupervisorに置き、SwiftPMでbuildする。

Contributing and security

See CONTRIBUTING.md before proposing a change. Please report vulnerabilities through the private process in SECURITY.md, not through a public issue.

The current documentation map is docs/README.md. Historical release notes live in docs/archive/releases/.

License

AIShell is licensed under the Apache License 2.0.