File-Based Context System

Talkie is heading toward a broader context system: corrections, snippets, routing rules, workflows, and automations all live in the same family, but they should not all be the same object.

This proposal is about making that family programmable from disk.

Instead of forcing every advanced use case through the UI, Talkie would discover behavior from one or more configured roots. A root could live in your Documents folder, or it could live inside a project as .talkie/.

.talkie/
  rules/
  tools/
  workflows/
  automations/

The point is not “run any random script from any folder.” The point is to give Talkie a file-first extensibility model that stays structured, observable, and git-friendly.

Why this direction

Talkie already has multiple adjacent systems:

• corrections and normalization
• snippets and shorthand expansions
• routing logic and context rules
• workflows
• automations

Those ideas belong together, but they do different jobs at different phases of the pipeline.

If every advanced use case becomes a new settings page or a one-off product feature, the system gets muddy fast. The concepts stop being defined by what they do and start being defined by where they happen to live in the UI.

The better model is phase-based:

1. Normalize
2. Expand
3. Route
4. Execute
5. Schedule

That gives us a clean litmus test:

• if it fixes text, it is a rule
• if it expands shorthand, it is a rule
• if it decides what should happen next, it is a rule
• if it does work, it is a workflow or tool
• if it decides when work runs, it is an automation

Core concepts

The proposed on-disk model has four top-level concepts:

• rules/
• tools/
• workflows/
• automations/

Rules

Rules are lightweight and declarative. They belong to one of three kinds:

• normalize
• expand
• route

A rule answers:

1. when does this apply?
2. what does it match?
3. what does it produce?
4. where is it allowed to run?

Example:

id: standup-template
kind: expand
name: Standup Template
enabled: true

when:
  event: dictation.finalized
  apps: [Slack, Notes]

match:
  type: exact
  text: "standup"

produce:
  insertTemplate: |
    Yesterday:
    Today:
    Blockers:

And a routing example:

id: summarize-for-slack
kind: route

when:
  event: dictation.finalized

match:
  type: regex
  pattern: "^summarize (.+) for slack$"

produce:
  runWorkflow: slack-summary
  vars:
    topic: "$1"

Rules decide. They should not directly execute arbitrary user code.

Tools

Tools are code-backed capabilities Talkie can invoke.

A tool is a folder with metadata plus an executable entrypoint:

tools/jira-ticket/
  tool.yaml
  run.ts
  README.md

id: jira-ticket
name: Jira Ticket
enabled: true
runtime: node
entry: run.ts
input: talkie/v1
timeoutMs: 10000

The key constraint is that Talkie remains the runtime. A tool is invoked as a subprocess. It receives JSON over stdin and returns JSON over stdout.

That means developers can use Node, Python, shell, or a compiled binary without Talkie having to become a custom host for every runtime.

Tools are not the primary place to model user-facing behavior. Workflows remain the preferred place to express Talkie-native behavior and multi-step execution. Tools exist for capabilities that are better implemented in external code while still staying structured, observable, and validated by Talkie.

Workflows and automations

Workflows stay Talkie-native. They remain the preferred place for expressing multi-step behavior and side effects.

Automations stay separate. They decide when a workflow or tool runs:

• on a schedule
• from an event
• later in the background

That separation matters. If you collapse rules, workflows, and automations into one object, the product gets harder to reason about fast.

Proposed directory layout

Here’s the v1 shape:

.talkie/
  rules/
    normalize-company-names/
      rule.yaml
    standup-template/
      rule.yaml
    summarize-for-slack/
      rule.yaml

  tools/
    jira-ticket/
      tool.yaml
      run.ts

  workflows/
    meeting-follow-up/
      workflow.json

  automations/
    morning-inbox/
      automation.yaml

Each capability is a folder instead of a single file because folders leave room for:

• metadata
• source files
• fixtures
• tests
• docs
• assets

That makes each item self-contained and versionable.

Runtime contract

The stdin/stdout contract is what keeps this system coherent.

Example tool input:

{
  "version": "talkie/v1",
  "event": "dictation.finalized",
  "text": "file jira fix login timeout",
  "vars": {
    "title": "fix login timeout"
  },
  "context": {
    "appName": "Linear",
    "bundleID": "com.linear",
    "source": "dictation",
    "workspacePath": "/Users/arach/dev/talkie",
    "timestamp": "2026-03-21T15:05:00Z"
  }
}

Example tool output:

{
  "effects": [
    {
      "type": "runWorkflow",
      "workflow": "create-jira-ticket",
      "vars": {
        "title": "fix login timeout"
      }
    }
  ]
}

This is the crucial boundary: tools do not get to mutate Talkie in-process. They return structured outcomes that Talkie validates and executes.

Guardrails

If this becomes “execute arbitrary scripts and hope for the best,” it is not a product feature. It is just a shell launcher with a logo.

The runtime needs guardrails:

• tools run out-of-process
• tools are time-limited
• Talkie captures stdout and stderr
• returned effect types are validated before execution
• Talkie never loads arbitrary user code in-process

Those constraints are what make the system viable.

What this unlocks

A file-based context system would make it possible to:

• keep project-specific behavior inside a repo
• share Talkie behavior over git instead of screenshots
• define snippets and routing rules without waiting on UI support
• build custom logic on top of Talkie without turning the app into a generic plugin host

It also gives us a better long-term way to organize the whole family of “context” features:

• rules shape meaning
• workflows do work
• automations decide when work runs
• tools provide code-backed capabilities

That feels like the right center of gravity.

Proposed rollout

The first version should stay narrow:

1. add configurable roots
2. discover rules/, tools/, workflows/, and automations/
3. validate and log discovered items
4. support declarative rules
5. support tools via stdin/stdout JSON
6. let rules reference workflows and tools by ID

Later phases can add:

• diagnostics UI
• dry-run tooling
• richer events
• slot extraction helpers
• templates and starter packs

The principle

Rules decide. Workflows do work. Automations decide when work runs. Tools provide code-backed capabilities.

That is the shape I want Talkie to grow into.