Codito

Native Windows work, screenshots, and frontend inspection

Choose Project access locally to use installed tools (uv, .NET, Git, SSH, Docker) for prompt-free project work. Outside cwd / declared external paths require Windows Deny/Allow/Always allow. This is cooperative native approval routing, not an OS sandbox; arbitrary native commands still have the Windows user's authority. Shell starts return a stable job ID and use a bounded event-driven wait for approval/state changes. If the start result is still non-terminal, long-poll/cancel that same job; never resubmit the intended command merely to continue an approval flow.

screen_list lists monitors; screenshot_capture sends a selected-display PNG to ChatGPT. Re-authorize screen:read when adding it to an existing connection. Windows offers Deny / Allow / Always allow for eligible display configurations; saved screen access is separate from file/shell permissions and is revocable in Settings.

Example tool sequence (replace screen_<id> with an ID returned by the first call):

screen_list(purpose="Choose the monitor to inspect")
browser_open(project_id="<project-id>", browser="firefox", url="https://example.com/",
             purpose="Open the requested page in Firefox")
screenshot_capture(project_id="<project-id>", display="screen_<id>", purpose="Inspect monitor")

Browser opening requires shell:execute and separate one-shot Windows approval, unless Full device access was explicitly selected for the calling project. It submits the URL to Firefox or the default browser; it cannot confirm page load. That ordinary-browser path has no mouse/keyboard control. Neither browser path adds elevation or secure-desktop capture. Notifications do not automatically bring Codito to the foreground. See the tool contracts, consent decision, and acceptance guide.

For local web UI work, Codito uses a separate agent-owned browser. The frontend_session_start, frontend_snapshot, frontend_inspect, frontend_act, frontend_source, and frontend_session_stop tools can start or reuse the configured loopback dev server, return viewport pixels plus semantic/CSS/a11y evidence, exercise bounded states such as hover/focus, and validate a DOM node's project-relative TSX source. They never reuse the user's normal browser profile or expose localhost through the relay. See the frontend guide.

Codito is a self-hosted, OAuth-protected bridge that lets ChatGPT work with registered projects on a user's Windows device, with Windows-approved access outside projects when requested. Registered roots stay local; explicitly requested device-read scopes/results pass through the relay. The device uses an outbound WebSocket tunnel.

MVP status: active development. Do not expose this build to untrusted users until every release-blocking item in docs/mvp-checklist.md is checked and the Windows sandbox test suite passes on the target build.

Related MCP server: Chat On Steroids

Repository layout

agent/              Windows per-user daemon, tray UI, and .NET security broker
relay/              Django/OAuth/MCP/ASGI relay
packages/protocol/  Shared Pydantic wire contracts and JSON Schemas
packages/vite-plugin-inspector/  Development-only JSX/TSX source metadata
deploy/             Immutable container and Compose deployment assets
docs/               Decisions, research, threat model, and runbooks

The public catalog contains 37 focused tools: project list/add/rename/remove, directory listing, file_read, text_search, file_patch, file_delete, execute_shell, shell_status, shell_cancel, screen_list, screenshot_capture, browser_open, six managed frontend_* tools, plus 16 language-neutral code_* tools for workspace summary, symbols, definitions/references, diagnostics/hover, context, hierarchies, impact/architecture/dependencies/related tests and explicit reindex. Old names remain hidden compatibility aliases. See the tool contract and Code Intelligence guide, and frontend inspection guide.

execute_shell takes the full command string, executor (powershell or cmd), timeout_seconds, project ID, cwd, purpose and idempotency key. It does not need an action enum. File tools accept an optional requested scope_path for approved external work; patch/delete retain exact hashes and recovery journaling.

Project settings offer Ask every time, Project access, and explicit Full device access. Existing legacy trust is not silently upgraded. Saved permissions can be inspected/refreshed and revoked individually in Settings. Full access still requires valid OAuth scopes and never permits locked-desktop capture or elevation. See local policy.

Install on Windows 11 x64

After a stable GitHub release is published, inspect and run the per-user bootstrap from PowerShell:

irm https://raw.githubusercontent.com/akbaramd/CoditoMcp/main/scripts/bootstrap-windows.ps1 | iex

The bootstrap resolves the latest stable release through GitHub's API and refuses an archive without the expected GitHub-published SHA-256 digest. It installs under %LOCALAPPDATA%\Codito\app\<version>, registers the daemon and desktop dashboard for the current user's sign-in, and keeps credentials/project paths in the separate local data directory. No administrator rights or system Python installation is required. Until production code signing is configured, Windows can display an unknown-publisher warning even though both outer and inner SHA-256 manifests are verified.

Developer setup

Install uv and .NET 8 on Windows. A system Python is not required.

uv sync --all-packages --all-groups
uv run ruff format --check .
uv run ruff check .
$env:MYPYPATH = "packages/protocol/src;relay;agent/src"
uv run mypy -p codito_protocol -p codito_relay -p codito_agent
uv run pytest
dotnet test agent/broker/Codito.Broker.sln --configuration Release

Useful commands are also available through just when installed. Copy .env.example only for local development; production configuration is created on the server and must never enter Git.

Security boundary

• OAuth authorization and the opaque device link are both required.

• Project roots are selected locally and absolute paths stay on the device.

• Isolated shell execution must fail closed if the Windows broker cannot prove its AppContainer and Job Object controls.

• full_access explicitly permits native file/shell/desktop authority without local prompts. Legacy native_trusted is not silently upgraded to this new mode.

Report vulnerabilities according to SECURITY.md.

Approved access to Windows outside projects

Use directory_list to request a drive/directory read without registering it as a project. Supply the origin project_id, scope_path=C:/, path="", purpose="Inspect the requested drive". Windows asks Deny, Allow once, or Always allow reading this folder. Always allow is local, revocable in Settings, and read-only. Broad scopes can expose private files to the requesting client.

For installed Windows tools such as uv, dotnet, or git, use execute_shell with a full command, for example dotnet build. The local project mode controls approval. Native commands use the installed tool PATH and the logged-in user's filesystem/network authority. Project cwd is not an isolation boundary. Legacy isolated mode remains blocked until changed locally.

Both relay and desktop must be updated for these capabilities. Refresh the ChatGPT connector tool list after updating.