ok so
Local-first automation for macOS
okso is a local-first automation toolkit for macOS that turns natural-language intent into reliable, reviewable command-line execution. It plans first, shows you what it will do, and then runs tools with guardrails and logs you can audit.
Start here
- Installation: install, upgrade, or uninstall the CLI.
- Usage: run your first request, approvals, and CLI flags.
- Configuration: model specs, caches, and runtime overrides.
What makes Okso different
- Local-first LLMs: llama.cpp-powered planning and execution keep data on your machine.
- Plan before action: a structured plan is generated and approved before any tool runs.
- Guarded tools: each tool has a strict schema and safety checks.
- Transparent logs: every step emits structured output you can inspect.
How it works (high level)
- Intent classification narrows the tool catalog and decides whether to gather web context.
- A pre-planner web search (optional) gathers snippets to ground the plan.
- The planner produces a structured tool-by-tool outline.
- You approve (or refine) the plan before execution.
- The executor runs each tool deterministically and records observations.
- The final answer is generated from the execution trace (with optional evaluation and replanning).
Documentation map
- Architecture: end-to-end flow and system boundaries.
- Execution model: planner + executor lifecycle.
- Tools: tool schemas, behaviors, and platform notes.
- Prompts: prompt templates and schema wiring.
- Schemas: JSON schema inventory and intent payloads.
- Contributor guides: formatting, tests, and workflow notes.
- Code quality standards: header policy, suppressions, and CI gates.
- Tech debt register: active
TD-###items and remediation targets. - Project overview: support, roadmap, and contribution expectations.