# AiMe - Local MCP Bridge for ChatGPT

> 🚀 **Quick Start for Users**: See the complete beginner-friendly guide at **[USER_GUIDE.md](USER_GUIDE.md)**!
>
> 1. Double-click **`Install-AiMe.cmd`** (automatically configures shortcuts and dependencies).
> 2. Double-click **`AiMe for ChatGPT`** on your Desktop -> connection URL is copied to clipboard!
> 3. Paste the URL into ChatGPT MCP Settings -> Connect and start working with your local files!

---

AiMe is a security-first Windows application that lets ChatGPT on the Chat
surface act as the planner and agent while using explicitly authorized MCP tools
on one or more computers.

The project is currently in discovery and clean-room design. Khai Hub and the
public Universal Body GPTHAND documentation are observable references only;
AiMe will not copy proprietary code, binaries, assets, credentials, or bypass
licensing or access controls.

## Project goals

- Connect ChatGPT Chat to a user-controlled computer through MCP.
- Keep ChatGPT as the only planner; AiMe does not delegate tasks to Codex CLI,
  Claude CLI, or another AI backend.
- Keep the local MCP server and computer off the public Internet.
- Enforce least-privilege profiles, explicit confirmation, and path boundaries.
- Record privacy-preserving audit events for every requested local action.
- Progress from Read to Modify, Control, Full, and narrowly brokered Admin
  capabilities only after each level passes its security gate.
- Support multiple independently revocable computers and profiles.
- Provide a Managed mode with login, organizations, bounded profile sharing,
  user/organization administration, and a separately constrained Platform Admin.
- Deploy the first managed control plane on NAS `kksm2` at
  `aime.kks.homes` through Cloudflare Tunnel without exposing the NAS origin.
- Deliver signed, staged, rollback-safe automatic Windows updates.
- Ship a Windows-first desktop experience that is testable in an isolated VM.

## Current state

The consolidated checkpoint is [Implementation Status and Next Steps](docs/IMPLEMENTATION_STATUS.md).
It separates implemented evidence from supported exposure, records explicit
non-claims, and provides the dependency-ordered resume plan. At the
2026-08-15 pause point, the full suite reports 1,284 tests: 1,279 passed, none
failed, and five were intentionally skipped. Typecheck passes, and the latest
independent review found no actionable issue in the production boundary that
denies generic Full-risk process presets from Modify.

The supported default stdio/tunnel route deliberately remains Read-only. Its
stdio startup rejects every schema-v2 profile containing a Modify capability,
and the Managed route applies one global `aime.read` tool-security scheme while
rejecting any Modify composition. A separate internal, pre-release local Modify
child and supervised tunnel composition now exist, but they are not an accepted
or documented release surface. The direct Modify child has no public npm start
script and is launched only as the supervised tunnel's MCP child. The supported
default stdio/tunnel route can also expose the profile-v2
`search_text_files` Read tool when the selected profile grants it. It performs
exact case-sensitive UTF-8 recursive search with a query capped at
256 UTF-8 bytes and no NUL, CR, or LF,
returns the first literal match per line with line and UTF-16 column data, and
supports the same local file/dir limits plus duration, depth, byte, file, and
match caps. Its audit surface is redacted to counters, the truncation reason,
and root/path fingerprints.

Tunnel admission now binds the SHA-256 of the exact profile bytes parsed and
validated by the parent to the same profile path opened by the native process
supervisor. The supervisor verifies that digest on its retained handle before
creating logs or processes, then denies write/delete replacement for the life
of the process tree. The derived digest is not stored in `tunnel.json` or sent
through child arguments, environment variables, readiness, or diagnostics.

An offline Windows release slice now builds stable native helper identities and
an unmanaged x64 packaged launcher, stages an exact allowlist of runtime files,
and produces an unsigned MSIX with SHA-256 block-map integrity through the real
Windows SDK MakeAppx tool. The manifest now exposes one app-list entry backed by
the native launcher, while live Start-menu/AppModel activation remains
unverified. Its launcher derives the package root and
Known-Folder config without ambient path variables, verifies the retained Node
leaf and offline Authenticode signature, passes only `SystemRoot` and `WINDIR`,
keeps stdin live, enforces one launcher per Windows session, and owns the Node
tree through a kill-on-close Job Object. An exact redacted lifecycle protocol
drives a standard status window and notification icon; duplicate launches reveal
the existing instance, and Stop first closes child stdin before a bounded
30-second Job-tree termination. Terminal setup/failure status remains dismissible
for up to ten seconds after the child exits instead of disappearing immediately.
When the staged launcher child reports that setup is required, one bounded Personal
Connect session can collect only a Tunnel ID and paths to an existing profile,
DPAPI-protected runtime-key blob, and tunnel client. A separate native helper
derives and prepares the private `%LocalAppData%\Ai&Me\state` boundary; Node and
the UI never receive the raw key. Successful no-replace finalization retries the
tunnel exactly once. This slice creates a missing `tunnel.json`; it deliberately
cannot replace a different existing configuration. Real Windows tests cover
hostile parent environment, exact argv/current directory, lifecycle rejection,
singleton launch, the setup/retry transition, graceful and forced descendant
cleanup, deterministic concurrent builds, staged module imports, and MakeAppx
pack/unpack.
This is not a signed installer or production activation result: package signing,
install/update behavior, publisher trust, live shell activation, and the external
tunnel-client distribution decision remain open. The launcher relies on
installed-MSIX package integrity for ancestor namespace protection, and the
Node-based stager requires an exclusive trusted build workspace.

The Windows-local Modify composition now combines schema-v2 profiles, native
SafeFs, Read and Modify tools, a bounded pending-action broker, a native
default-Deny confirmation UI, redacted JSONL/protocol audit, and an MCP stdio
transport. Real Windows MCP tests cover `create_text_file`, exact bounded
single-file `apply_patch`, expected-SHA-256 `replace_text_file`, and exact-
`changeId` `rollback_change`. The patch route reads the current UTF-8 bytes,
applies strictly ordered non-fuzzy hunks, binds confirmation to the old, patch,
and resulting digests, publishes through the existing atomic replacement, and
supports idempotent retry plus exact rollback. Tests also cover denial without
side effects, redaction, restoration of the original bytes, and native handle
cleanup. `preview_patch` is now implemented as an internal metadata-only
Modify preview, but it still is not a public release-surface tool. Move and
delete remain unavailable at the Modify surface. The profile-gated
`search_text_files` tool is available through the supported default Read
stdio/tunnel route and uses a dedicated cancellable native helper so ordinary
reads remain isolated. The repository still has no accepted public release.
This
internal route still lacks production package/executable signing, a protected
installed-and-activated release proof, operator repair UI, and end-to-end Chat
confirmation evidence, so it remains a development proof rather than a release
candidate.

Phase 5 now has a lower-level internal profile-v2 `run_process_preset`
mechanism proof. Its direct test composition exposes asynchronous
`start_process_preset`, `get_process_task`, and `cancel_process_task` MCP tools
while keeping the executable, executable SHA-256, argv, cwd, and workspace root
profile-owned. Each start requires exact local default-Deny confirmation. The
native runner starts the standard-user tree suspended, assigns Job Object
process and memory limits before resume, and bounds wall time, cancellation
grace, stdout, stderr, total output, and UTF-8 pagination over one combined
cursor. Those controls are containment, not a sandbox: argv-referenced scripts,
imports, package hooks, config, and plugins remain mutable, and
`network:not_enforced` is explicit. The production local Modify runtime and
stdio host therefore reject `run_process_preset` profiles before acquiring
owners. The mechanism remains internal Full-risk evidence until a Full-session
gate or dedicated structured wrapper proves a narrower boundary. Managed and
ordinary Read do not expose it, task and request state is in memory only, stdin
and interactive input are unavailable, Git is not included, and no public Chat
or live packaged-activation claim is made.

SafeFs provides handle-relative single-file publication, ordered flush and
reconciliation, and bounded private rollback artifacts. This is best-effort
ordered NTFS recovery, not a filesystem transaction or a hostile same-user
compare-and-swap guarantee. A `repair_required` state stops every mutation in
that runtime/profile until a future local operator-repair workflow resolves it.
The broader desktop UX, multiple-device and multi-user web experience, `kksm2`
deployment, signed updater, installer, and release hardening remain incomplete.

The latest executable proof adds a local Managed-mode chain. A separately
signed local approval is consumed once, an explicit Ed25519 or ECDSA-P256
device proof issues a revocable schema-v2 certificate, and every reconnect
requires a fresh algorithm-and-fingerprint-bound challenge. Windows P-256 keys
can now be created and used through a separate current-user Software KSP helper
without exporting private key bytes to Node. A headless enrollment coordinator
now derives a short-lived public intent from that identity, validates an exact
server-authenticated proposal, requires explicit local confirmation, verifies
the canonical schema-v2 pairing challenge and certificate claims before using
the signing oracle, and returns only after a protected credential store
acknowledges an atomic create. The Windows store now validates the exact
credential record and certificate binding, then publishes an identity-bound
DPAPI CurrentUser blob through a private, no-replace native transaction. It
can now be consumed by a separate Windows post-enrollment bootstrap that opens
the fingerprint-pinned CNG identity and starts the existing authenticated WSS
reconnect supervisor without recreating the key or replaying enrollment. It
does not implement the broker, confirmation UI, or durable repair outbox. A
five-minute signed Read lease then binds one tenant/user/connection/device/profile route to
the existing local Read boundary.
A bounded Streamable HTTP relay has also been exercised end to end through that
outbound device session, including session deletion, Host/Origin checks,
pre-authentication request admission and body limits, durable session-open
audit, and bounded shutdown. A local public-application router now composes
authorization-server metadata and JWKS, explicit authorization decisions, the
OAuth token endpoint, protected-resource metadata, JWT verification, and the
MCP relay. Its end-to-end test performs authorization-code and PKCE exchange,
verifies the resulting RS256 access token, and calls the existing Read tools.
Managed Read tool discovery emits the required OAuth `securitySchemes` both at
the top level and in the compatibility `_meta` mirror. The scheme is globally
`aime.read`; the MCP server refuses to combine it with Modify, while stdio
startup separately rejects Modify profiles rather than silently downgrading
them.

The repository also contains a separate real-socket device-wire proof. It now
includes authenticated device-wire handoff, authenticated device-session
binding into the session hub, a bounded loopback WebSocket carrier, and the
original bounded multiplexed TCP transport proof. These local slices enforce
strict framing and sequence order, apply backpressure, heartbeat, and lifecycle
limits, and close fail-closed on malformed or oversized traffic. They are still
local proofs rather than a deployed service: there is still no public HTTPS
service, wired and real-database-verified authorization-code store, durable tenant store, durable
signing-key ring, login/consent UI, or production control plane. The complete
device-side reconnect supervisor now creates a completely new authenticated WSS
connection after transient loss, uses bounded exponential backoff with jitter,
drops all prior logical streams, and stops immediately on authentication or
protocol denial. It intentionally receives no gateway-generated connection ID;
the gateway remains the authority for fresh connection and lease binding. A
real loopback reconnect test now proves that the second handshake receives a
fresh gateway connection ID, the first lease fails with `route_mismatch` before
the device opens a stream, and a newly bound lease reaches the existing Read
tools. This remains a local test-only WebSocket proof, not deployed TLS/WSS or
Chat-surface evidence. A new managed network host now owns one Node HTTP server
for both the public OAuth/MCP application and the authenticated device WebSocket
gateway, without taking ownership of tenant or authority state. Its bounded,
idempotent shutdown fences HTTP admission, stops new TCP accepts, closes active
device sessions, and force-closes owned HTTP sockets after the configured drain
deadline. A managed consumer gateway runtime now composes that host with the
OAuth metadata, authorization, token, JWT-verification, MCP relay, signed route
leases, and the existing authority runtime. It derives tenant, subject, and
connection identity only from verified access-token claims, accepts only an
exact non-secret device/profile route binding, and fences lease issuance during
shutdown. It still does not listen publicly, configure TLS, load deployment
secrets, or choose a tenant/pairing user experience by itself.

An unwired PostgreSQL authorization-code adapter and schema migration now add a
fixed cross-process advisory-lock boundary for replay/capacity, independent
approval replay fences with bounded retention, digest-only consume-on-attempt,
and strict persisted-row validation. Deterministic transaction tests pass, and
an opt-in integration test covers two independent pools, one-winner redemption,
approval replay, and wrong-binding burn across reopen. No disposable PostgreSQL
URL is configured on this host, so that real-database integration is explicitly
skipped and this is not production durability evidence. The Windows suite
now reports 1,284 tests. On 2026-08-15, 1,279 passed, none failed, and five were
skipped: the opt-in PostgreSQL integration lacked an explicit disposable
database URL, and four cases are intentionally POSIX/non-Windows-only.

**Chat feasibility gate:** a scoped `GO` was recorded on 2026-08-13 after real
Chat calls reached the Windows VM, returned a unique allowed canary, denied an
outside-root request, survived a controlled reconnect, and stopped without an
AiMe orphan process. This proves the product premise for continued investment,
not production readiness. The tested PC path required Chat `High`; `Pro` did
not reliably invoke the private app on that account/device.

The first Personal Connect core can now publish a validated Read profile
through a parent-pinned, handle-relative atomic native transaction and finalize
a tunnel configuration from a DPAPI-protected key blob. Windows profile loading,
Windows tunnel-config loading, and durable audit appends now use the native
no-follow filesystem boundary. A bounded native setup dialog now collects the
four non-secret inputs needed to create a missing fixed-state configuration and
hands them to that same finalizer. Its current `config_ready` state does not
claim that the tunnel or ChatGPT app is connected. Personal mode still requires
a user-owned OpenAI tunnel, an already protected runtime-key blob, an existing
profile, the external tunnel client, and private ChatGPT app setup. Replacing a
different existing `tunnel.json`, creating those prerequisites, a complete
first-run wizard, and the managed Khai-like connection service remain
unimplemented. The repository now proves local approval, device authentication,
single-use pairing, the headless confirm-before-sign enrollment lifecycle,
authenticated device-session binding, bounded routing, the
HTTP relay seam, and a separate loopback WebSocket carrier with trusted-WSS
tests, but those authorities still run through one local composition root. It
opens and replays the authenticated authority journal, hydrates the device-wide
revocation fence, binds credentials to leases and device sessions, and closes
sessions before authority state. This is still a local single-process
foundation, not a service: real login/consent, deployed OAuth endpoints, public
HTTPS/WSS, durable tenant storage, cross-process coordination, and deployment
remain unimplemented.

## Documentation

Start with:

- [Implementation status and next steps](docs/IMPLEMENTATION_STATUS.md)
- [Product requirements](docs/PRODUCT_REQUIREMENTS.md)
- [Capability and permission model](docs/CAPABILITY_AND_PERMISSION_MODEL.md)
- [Delivery roadmap](docs/ROADMAP.md)
- [UX and multi-device plan](docs/UX_AND_MULTI_DEVICE_PLAN.md)
- [Web control plane and RBAC plan](docs/WEB_CONTROL_PLANE_AND_RBAC_PLAN.md)
- [Deployment and automatic update plan](docs/DEPLOYMENT_AND_UPDATE_PLAN.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Running locally](docs/RUN_LOCALLY.md)

See [the documentation index](docs/DOCUMENTATION_INDEX.md) for the complete
registry, evidence reports, and documentation governance rules.
