> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/public-website/src/content/blog/hook-events-to-cockpit.md).

# From hook events to a local cockpit

FactionOS starts with a narrow idea: when an agent workflow emits local events, the operator should be able to see those events as useful operating state. A hook event by itself is only a signal. A cockpit turns a sequence of signals into context a human can use.

This article describes the product direction at a high level: local agent events should become readable cockpit state before any optional handoff exists.

### The local event boundary

Agent events can describe sensitive development context: session names, task notes, command outcomes, file references, validation status, and human review points. FactionOS treats those signals as local development state first.

That default is why the [security page](https://github.com/AI-with-Apex-VIP/factionos/tree/main/security/README.md) and [local-first architecture post](https://github.com/AI-with-Apex-VIP/factionos/tree/main/blog/local-first-agent-observability/README.md) both avoid surprise data-path language. A useful cockpit can be local, explicit, and scoped.

### From event to state

The practical flow is simple:

1. A local tool emits a structured event about a session or task.
2. The local runtime normalizes the event into a stable shape.
3. The cockpit presents the event as status, history, review context, or a validation signal.
4. A human uses that state to decide what to inspect next.

The important part is not the volume of data. It is whether the state helps a operator answer concrete questions: What is active? What changed? What failed? What needs review?

### Why normalization matters

Raw hook output can be noisy. A cockpit should not require an operator to read unstructured logs. It should show reviewable labels, counts, statuses, timestamps, and scoped messages that fit the product contract.

The [how it works page](https://github.com/AI-with-Apex-VIP/factionos/tree/main/how-it-works/README.md) explains that flow without turning this website into a runtime surface. Setup and usage details belong in the [public docs](https://faction-os.gitbook.io/faction-os-docs), which are hosted as a separate destination.

### What stays separate

Hosted persistence, hosted identity, remote execution, inbound commands, and executor behavior are separate product concerns. Those capabilities require authorization, data handling, tests, documentation, and launch evidence.

The current editorial job is narrower: explain how local hook events can become readable cockpit state while keeping the default data boundary clear.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/public-website/src/content/blog/hook-events-to-cockpit.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.