koda

Koda is the development environment for mashin. It is not a chatbot added to an IDE. Koda IS the IDE. The entire environment is intelligent.

Most users never write mashinTalk directly. They tell Koda what they want: “Build me something that triages my email by urgency.” Koda investigates, designs the machine, generates the plan, and explains what it built and why. You review, adjust, and deploy. This is the first of three levels of working with mashin: say what you want, read and refine the plan, let the platform handle the rest.

Koda’s cognitive operations are themselves mashin machines, so they are governed, auditable, and inspectable. The IDE practices what it preaches.

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 computer	Production execution on mashin.live
Shared cloud	Team collaboration with shared state
Shared local	Distributed execution 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
• Computers - The runtime environment where machines live
• Machine Anatomy - The structure koda helps you build
• Governance - How koda’s own operations are governed