koda
Koda is the development environment for mashin. It is not an assistant or chatbot bolted onto an editor. The entire interface is intelligent: you work in projects, books, and sessions, and koda provides context-aware help throughout. koda’s cognitive operations are themselves mashin machines, so they are governed, auditable, and inspectable.
Projects, books, and sessions
Work in koda is organized in a hierarchy:
| Level | Purpose |
|---|---|
| Organization | Your team or company. Contains projects and members. |
| Project | A collection of related machines. Has its own settings, credentials, and history. |
| Book | An investigation context within a project. Where you do focused work. |
| Session | A single interaction within a book. Conversations, commands, and results. |
You might have a project called “Customer Support” with books for “Ticket Classifier”, “Response Generator”, and “Escalation Rules”. Each book holds the sessions where you built, tested, and refined that machine.
Intelligence is ambient
In most AI-powered IDEs, you invoke the assistant: click a button, open a chat panel, type a question. In koda, intelligence is ambient. It is woven into the entire interface:
- When a machine run fails, koda surfaces the failure proactively with context about what went wrong
- When governance denies a step, koda explains which rule matched and suggests how to adjust permissions
- When you edit a machine, koda has full awareness of the project context: other machines, their contracts, recent runs, known issues
- Signals (incoming events, failures, cost thresholds) appear in the signal bar without you asking
Signal-driven environment
Koda watches for things that need attention and surfaces them as signals:
- A machine run failed
- A governance violation occurred
- Token costs exceeded a threshold
- An A2A message arrived from another machine
- A test suite has new failures
Signals appear in the Signal Bar. You do not need to poll dashboards or check logs. The environment tells you when something needs your attention.
Full application introspection
Koda has access to the full application graph: every machine, every run, every governance decision, every version in the evolution ledger. When you ask koda about a machine, it does not just search documentation. It reads the machine’s source, its execution history, its governance rules, and its test results.
This is the three-tier context contract:
| Tier | What koda sees | Example |
|---|---|---|
| Guaranteed | Always available in every session | Current machine source, project structure, recent runs |
| Expandable | Available on request | Historical runs, other project machines, evolution history |
| Restricted | Not available without explicit grant | Other organization data, credentials, PII |
Cognitive operations as machines
Every cognitive operation koda performs is itself a mashin machine in the @system/koda/* namespace:
@system/koda/kardia- koda’s core reasoning@system/koda/memory- Context and memory management@system/koda/awareness- Signal processing and proactive surfacing
Because these are machines, they are governed and auditable. You can inspect what koda did, why it made a suggestion, and what data it used. This is the Smalltalk property: the development environment is built from the same primitive as the things it builds.
Overriding koda behavior
If you want koda to behave differently for your project, write a machine with a matching name. For example, creating @myorg/kardia in your project overrides @system/koda/kardia. Your custom reasoning machine inherits the same interface contract but implements project-specific logic.
Execution environments
Koda can execute machines in different environments:
| Environment | Use case |
|---|---|
| Local desktop | Development and testing on your laptop |
| Cloud cell | Production execution on mashin.live |
| Shared cloud | Team collaboration with shared state |
| Shared local | BEAM distribution across local machines |
Execution is location-transparent. The same machine runs the same way regardless of where it executes. The behavioral ledger records which environment each run used.
Try it
Open a project in koda and create a new book for a machine you want to build. Start a session and describe what the machine should do. Watch how koda uses the project context (existing machines, available permissions, recent runs) to help you write the implementation.
Next steps
- Platform Overview - How all the platform components fit together
- Cells - The runtime environment where machines live
- Machine Anatomy - The structure koda helps you build
- Governance - How koda’s own operations are governed