# Sneakoscope Codex
**Make Codex work explainable, bounded, and test-backed.**
[](https://github.com/mandarange/Sneakoscope-Codex/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/sneakoscope)
[](#requirements)
[](LICENSE)
Sneakoscope Codex (`sks`) is an open-source local tool for the Codex CLI and Codex desktop app. It adds a macOS control center, bounded agent workflows, repository context, and evidence checks for SKS releases.
Current package: **SKS 10.7.3**, prepared for npm publication.
[Latest release notes](https://github.com/mandarange/Sneakoscope-Codex/releases/latest)
· [npm package](https://www.npmjs.com/package/sneakoscope)
· [Changelog](CHANGELOG.md). Install the latest stable release from npm.
Ordinary work stays with the main agent. Optional Jev decisions use OpenRouter
with cloud consent; source indexing and safety checks run locally. The default
`essential` verification profile keeps safety checks active without requiring
completion-proof rituals on every turn. `strict` adds those checks. SKS's npm
release workflow requires its own current test and artifact evidence in either
profile. See [verification profiles](docs/essential-trust.md).
## SKS Center — one place for your Codex setup
On macOS, **SKS Center** puts connections, subagent model choices, updates,
and diagnostics in a native menu bar app. Open the SKS menu bar icon and choose
**Open SKS Control Center…** to manage your setup without memorizing CLI commands.
*Native SKS Center UI with an example configuration. Models and available
reasoning efforts depend on your connection's current catalog.*
| Page | What you can manage |
| --- | --- |
| **Connections** | Codex-LB, OpenAI OAuth, OpenRouter, and model visibility. |
| **Subagent Models** | Separate lists per connection, a default option, reasoning effort, and criteria for Jev. The same model can have different efforts for different work. |
| **Decisions** | Jev's decision mode and cloud consent. |
| **Settings** | Naruto's execution preference and app settings. |
| **Image Generation** | Image mode, supported model choices, and provider setup. |
| **MCP Servers** | Connected tools and server configuration. |
| **Updates & Diagnostics** | Available updates, operation progress, logs, and health checks. |
After installing SKS, install or rebuild the macOS app with:
```sh
sks menubar install
```
Interactive global macOS installs can build it automatically. Dependency, CI, and
piped installs skip the menu bar setup; scripts can opt in with
`SKS_POSTINSTALL_MENUBAR=1` or opt out with `SKS_POSTINSTALL_NO_MENUBAR=1`.
See [connection setup](docs/codex-lb.md), [subagent model lists](docs/naruto.md#connection-specific-subagent-lists),
and [image generation](docs/image-generation.md) for the underlying settings.
## Quick start
### Requirements
- **Recommended: the latest patch release of Node.js 24 LTS.** Get it from the [official Node.js releases](https://nodejs.org/en/about/previous-releases).
- npm, Git, and a current Codex CLI or supported Codex desktop host.
- Building SKS Center on macOS also requires Xcode Command Line Tools and Swift;
the installer reports `xcode-select --install` if the tools are missing.
- For source development and tests, see the locked dependency compatibility ranges in [Contributing](CONTRIBUTING.md#local-setup). CI uses the 24.x line.
The published CLI's declared `package.json` engine floor is still `>=20.11`.
That is separate from the development/test requirements above; Node 20 is now
end-of-life, so use a supported LTS release for a new installation.
### Install SKS globally
Install SKS once for your user account so `sks` is available across projects:
```sh
npm install --global sneakoscope@latest
sks doctor --fix --global-only --yes
sks --version
```
Run these commands in your terminal. The global-only Doctor step reconciles
user-level SKS skills and configuration, and reports any setup blockers.
Make sure your npm global binary directory is on `PATH`.
Alternatively, the verified installer performs the global npm installation,
runs Doctor, and checks that `sks` on `PATH` resolves to the installed version:
```sh
npm exec --yes --package=sneakoscope@latest -- sneakoscope install --yes
```
### Add project context
Global SKS hooks and skills apply across projects. From a project root, create
its local context and ignore rules with:
```sh
sks bootstrap
sks doctor --json
```
Then open the project in Codex. Refresh its context and ask for ordinary work
directly in the conversation:
```text
$sks-align
Fix the failing test and verify the changed behavior.
$sks-review
```
`sks bootstrap` initializes the project's SKS files. `$sks-align` builds the
source index and refreshes managed guidance. Choose `$sks-naruto` or `$sks-work`
when you explicitly want child agents; enabled Jev can also select parallel
work when it judges that the task has independent parts.
## Update an existing installation
Run this from your project root in a terminal:
```sh
sks update
sks --version
sks doctor --json
```
`sks update` updates the **global** SKS package, verifies the installed command,
and reconciles SKS-managed skills, hooks, configuration and SKS Center where
available. Cleanup follows the current package's manifest and ownership markers
regardless of the previous version, including mixed leftovers from interrupted
installs or a missing old generation manifest. Running it again when already
current still repairs the managed setup. It also repairs the known ignored
Codex settings and refreshes managed guidance. User-authored text, credentials
and explicit preferences are preserved. A required cleanup failure blocks
completion and is reported with its recovery action.
To check available updates first, run `sks update check`. For a repair without
requesting a newer package, run `sks doctor --fix` yourself in the terminal.
## What you get
| Need | SKS provides |
| --- | --- |
| Keep work focused | Answers, tiny edits, ordinary implementation, reviews, and DB work run directly in the main agent. Naruto delegates through official Codex subagents when explicitly requested or selected by Jev. |
| Keep context bounded | TriWiki indexes repository code into context that can be checked against source. |
| Reuse project memory | Opt-in Jev intake stages mission candidates; explicit promotion validates durable records separately from the code index. |
| Know what actually ran | Diagnostics report measured checks; release gates bind tests and package evidence to the candidate commit. |
| Recover safely | Doctor and update flows report a concrete recovery action when a check needs attention. |
| Operate locally | The CLI works without a hosted control plane; macOS users can also use SKS Center. |
`$sks-align` refreshes the thin managed guidance against current official Codex
references and rebuilds TriWiki. Update and user-run `sks doctor --fix` share
that maintenance and repair known ignored configuration settings. User text
and model choices are preserved. See [harness maintenance](docs/align-modernization.md).
### New in 10.7.0
- **A smaller command surface:** duplicate and unused commands were removed;
use `sks help