> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kernel — Eyes and Hands

> How Kernel CLI gives the expanded being structured perception, semantic action, pixel fallback, and machine awareness.

# Kernel — Eyes and Hands

Kernel CLI is where AI meets the operating system. It reads the structures the
OS already maintains, acts through the strongest available capability, and
falls back to rendered pixels only when structure is absent.

<Card title="Kernel CLI documentation" icon="microchip" href="/kernel-cli">
  Read the canonical installation, workflows, platform boundaries, safety model,
  and command reference.
</Card>

## Eyes: Structured Perception

The first question is not "what does the screenshot look like?" It is "what
does the machine already know?"

```text theme={null}
Machine and app data
        ↓
Windows and session state
        ↓
Accessibility and target handles
        ↓
Rendered-text OCR
        ↓
Screenshot evidence
```

| Surface              | What it contributes                                                             |
| -------------------- | ------------------------------------------------------------------------------- |
| Machine state        | Processes, power, devices, ports, services, security, logs, and session context |
| Windows and displays | Ownership, bounds, focus, geometry, and multi-display coordinates               |
| Accessibility        | Roles, labels, values, enabled state, focus, and available actions              |
| Targets              | A compact interaction map with guarded handles and preferred write paths        |
| OCR and capture      | Rendered text and visual proof when semantic structure is missing               |

The eyes are broad because desktop failure is not always a visual problem. A
missing app may be a crashed process. A failed action may be a permission or
session problem. A network dialog may be the visible symptom of a proxy, route,
or service state.

```bash theme={null}
kernel-cli --json doctor
kernel-cli --json report
kernel-cli --json snapshot
kernel-cli --json targets --top 20
```

## Hands: Capability-First Action

Kernel CLI chooses the most semantic available write path:

```text theme={null}
App-native action
        ↓
Accessibility press / set / menu / target action
        ↓
Verified keyboard input
        ↓
Pointer or device-level fallback
```

| Action surface                  | Best use                                                                    |
| ------------------------------- | --------------------------------------------------------------------------- |
| `act`                           | Resolve a guarded target handle, preview the backend, and verify the result |
| Accessibility actions           | Press, set, select, reveal, or invoke a named UI element                    |
| App, window, and menu control   | Change explicit desktop state without guessing coordinates                  |
| Type, key, and paste            | Enter text in a known target context                                        |
| Click, scroll, and drag         | Handle visual-only or direct-manipulation UI                                |
| Platform script or device input | Explicit fallback for workflows that require it                             |

The preferred loop preserves the state identity that produced the target:

```bash theme={null}
kernel-cli --json targets --app "TextEdit" --intent save --top 20
kernel-cli --json act '<target_id>' --snapshot '<snapshot_id>' --dry-run
```

The dry run answers which target and write backend would be used. The snapshot
guard refuses stale state instead of blindly applying an old handle to a changed
screen.

## Semantic Does Not Mean Infallible

Accessibility is stronger than a coordinate guess when an app exposes a useful
semantic tree, but not every element wires every advertised action. Custom
renderers, games, canvases, decorative links, hidden or throttled windows, and
incomplete accessibility implementations may require another path.

The rule is therefore:

```text theme={null}
prefer semantics → verify → fall back deliberately
```

It is not:

```text theme={null}
assume every named element must work
```

Kernel CLI keeps OCR, screenshots, pointer input, and stricter no-focus or
no-cursor policies available for those differences.

## More Than Desktop Automation

The body also senses the machine that carries the desktop:

```bash theme={null}
kernel-cli --json hardware
kernel-cli --json stats
kernel-cli --json security
kernel-cli --json process --sort cpu --top 5
kernel-cli --json ports
kernel-cli --json services
kernel-cli --json schedule
```

This is the difference between merely moving a cursor and understanding the
conditions around an action. The agent can diagnose before it acts.

## Cross-Platform Body, Platform-Specific Senses

Kernel CLI offers one behavioral order across three operating systems, but the
body is not identical on each one:

* **macOS** exposes the broadest native observation and control surface.
* **Linux** depends on the interactive desktop, AT-SPI, display server, and
  helper availability. Pure Wayland may restrict global input or capture.
* **Windows** centers on UI Automation and Win32 in the interactive user
  session, with OCR dependent on language support.

`kernel-cli --json doctor` is the live answer. A platform label alone is never
enough to prove that a sense or action is available in the current session.

## Browser Tools and Kernel Tools

Browser DOM/CDP tools and Kernel CLI are complementary:

| Browser tool                                                  | Kernel CLI                                                           |
| ------------------------------------------------------------- | -------------------------------------------------------------------- |
| Deep browser-native DOM, network, console, and page lifecycle | Windows, apps, accessibility, system telemetry, and OS-level control |
| Strongest inside the browser                                  | Broadest across the local operating system                           |
| Page and browser process context                              | Machine and interactive desktop context                              |

Use the browser-native surface for browser internals. Use Kernel CLI when the
workflow crosses applications or needs OS state. A workflow can use both.

## The Harness Holds the Reins

Direct Kernel CLI is raw capability. NIIA places a human authorization boundary
in front of control:

```text theme={null}
Kernel CLI = eyes and hands
NIIA       = permission to use the hands
```

```bash theme={null}
niia observe targets --app "TextEdit" --json
niia control unlock --scope full --duration 30m
niia control act '<target_id>' --snapshot '<snapshot_id>' --dry-run --json
niia control lock
```

The capability body and the authorization harness are deliberately separate.
See [The Harness](/philosophy/niia-and-kernel/06-the-harness) for that boundary.

## The Expanded Interface

The expanded being can now move across several complementary surfaces:

* **Terminal:** interactive CLI sessions and tools.
* **Operating system:** Kernel CLI observation, control, and machine telemetry.
* **Remote machines:** Monolex transport and headless session surfaces.
* **External services:** MCP and CLI integrations.

The question is not whether the being has eyes and hands. The useful question
is whether it can show what it saw, which capability it chose, who authorized
the action, and how it verified the result.

<CardGroup cols={2}>
  <Card title="Kernel CLI Workflows" icon="route" href="/kernel-cli/workflows">
    Follow the observe, dry-run, act, verify, and NIIA-gated loops.
  </Card>

  <Card title="Kernel CLI Reference" icon="book" href="/kernel-cli/reference">
    Inspect commands, permissions, platform behavior, audit, and MCP.
  </Card>
</CardGroup>