@supercorks/krnl 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# Kernel CLI
+
+Connect [Kernel](https://app.krnl.work) to Codex on your Mac. Start a task from Kernel in Plan or
+Work mode, then open the same task in Codex. Conversations and approvals stay in Codex; Kernel
+shows execution status and a direct link.
+
+## Install and connect
+
+Requires **macOS, Node 22–24, pnpm, and a signed-in Codex desktop installation**.
+
+```bash
+pnpm add -g @supercorks/krnl
+krnl login
+krnl connect codex
+```
+
+`krnl login` opens Kernel in your default browser. Sign in with your invited Kernel account and
+choose **Connect CLI**. Return to Terminal when the browser says the login is finishing.
+
+`krnl connect codex` asks once for access to **all current and future compatible saved Codex
+projects** for that Kernel account. It registers this Mac, installs status hooks, and starts a
+background companion that runs at login. It prints the exact Codex command and `/hooks`
+instructions if the new hooks need review. Review the eight Kernel hooks and restart open Codex
+tasks afterward. The companion detects completed review automatically.
+
+Open **Settings → Integrations → Codex** in Kernel to map an organization or project to a saved
+Codex project. Your Mac and saved projects appear automatically. Launches stay disabled until setup
+is ready; one unavailable project does not disable healthy projects.
+
+No repository checkout, build tools, copied IDs, or per-folder authorization commands are needed.
+Installing the npm package alone does not start a service or change Codex configuration.
+
+## Commands
+
+| Command                 | Purpose                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `krnl login`            | Sign in through Kernel in the browser.                                       |
+| `krnl connect codex`    | Connect, resume interrupted setup, or repair/update this Mac’s installation. |
+| `krnl status`           | Check the account, connection, saved project count, and remaining setup.     |
+| `krnl disconnect codex` | Revoke this connection and remove its login service; keep your CLI login.    |
+| `krnl logout`           | Disconnect and remove the local CLI login.                                   |
+
+For another Kernel deployment, use `krnl login --origin https://your-kernel.example`. HTTP is
+accepted only for loopback development. Log out before switching deployments.
+
+To update:
+
+```bash
+pnpm add -g @supercorks/krnl@latest
+krnl connect codex
+```
+
+Repeated connection reuses the machine identity. Review changed hook commands in `/hooks` if Node
+moved. After updating Node, run `krnl connect codex` to refresh the service’s executable path.
+
+## Projects and compatibility
+
+The companion uses saved project identities from Codex’s app-server. Initial support covers
+projects with one accessible local folder. Git mappings default to a new worktree from
+`refs/remotes/origin/HEAD`; choose **Existing folder** under the mapping’s **Advanced** settings if
+needed. Non-Git projects use their saved folder. Missing folders, multi-root projects, and disabled
+project hooks are explained beside that project in Kernel.
+
+Tested Codex capabilities: desktop **26.901.51231** with bundled CLI **0.153.4**. The companion prefers
+`/Applications/ChatGPT.app/Contents/Resources/codex`, falling back to `codex` on PATH. The app-server
+capabilities are experimental, so other Codex versions require verification.
+
+The companion releases its first-turn app-server after completion or a request for input. Continue
+in desktop after that release; an interrupted structured question may be asked again. Kernel
+observes Running/Done across later desktop turns through hooks. It does not answer questions or
+approve commands.
+
+Existing companion installations keep their allowlist until you explicitly upgrade through
+`krnl login` and `krnl connect codex`. The upgrade retains their machine identity, mappings, and
+handoff history when the existing connection is still authorized.
+
+## Local data and troubleshooting
+
+The executable is copied to a stable location under
+`~/Library/Application Support/Kernel/Codex/bin/`. Hook and service paths do not depend on global
+package folders or temporary installer caches. launchd services live under `~/Library/LaunchAgents`.
+Closing Terminal does not stop the service.
+
+CLI credentials use macOS Keychain service **Kernel CLI**; machine credentials use **Kernel Codex
+companion**. Codex credentials stay local. Browser URLs never contain these credentials. The
+browser returns a short-lived authorization code to a temporary `127.0.0.1` callback, protected
+with state and PKCE. CLI sessions last 90 days; run `krnl login` again after expiry.
+
+Run `krnl status` first when disconnected, then `krnl connect codex` to repair setup. If Kernel
+revoked the Mac remotely, sign in again with `krnl login` before reconnecting. If revocation cannot
+reach Kernel, the disconnect command stops the local service and asks you to retry online.
+
+Disconnect and logout preserve Codex tasks, local creation receipts, and worktrees. Hooks retain
+only lifecycle metadata for tasks created by this connection. Neither transcripts nor attachment
+contents are uploaded. Keep receipts intact when investigating an uncertain launch; the companion
+will reconcile creation before retrying an acknowledgement and will not repeat an uncertain turn.
+
+Homebrew, a native setup app, and a one-command `npx` setup flow are not included in this release.
+
+## Bundled third-party software
+
+This executable includes Zod under the following license:
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.