# x — A Governed Execution Runtime for Humans and Agents
> Runtime > prompt
> Evidence > explanation
> Causality > logs
`x` is a **local-first execution runtime** that turns real shell commands
into **durable, causal, machine-readable evidence**.
It is designed to be the missing layer between:
- humans running commands
- and LLMs / agents trying to reason about what actually happened.
---
## Why does `x` exist?
Today, when something breaks, we do this:
- copy random terminal output
- paste partial logs into an LLM
- paraphrase what we *think* happened
- hope the model infers the rest.
This is not evidence.
This is noise.
`x` exists to create a **hard trust boundary**:
> If it ran with `x`, it is evidence.
> If it didn’t, it’s noise.
---
## What is `x`?
`x` is:
- a thin runtime wrapper around your shell
- a governed execution recorder
- a causal trace generator
- a semantic memory substrate
- a projection engine for prompt evidence
It captures:
- the exact command
- stdout and stderr
- exit code
- timestamps and duration
- working directory
- optional Git state
And stores them as **immutable JSON artifacts** on disk.
---
## What is `x` NOT?
`x` is not:
- a logger
- a terminal
- an agent
- an observability platform
- a cloud service
- a knowledge graph
- a monitoring system
It does not:
- summarize
- reason
- decide
- retry
- fix
- infer
It only records reality.
---
## The core idea
Instead of logs, `x` produces a **Context Graph**:
- each execution is a node
- sessions are causal containers
- ordering is strict and explicit
- derivations can be linked
- projections are deterministic views
This gives humans and LLMs something they never had:
> a governed, causal, replayable view
> of what actually happened.
---
## A 30-second demo
```bash
# start a new causal session
exec-start "debug nginx config"
# run commands through x
x nginx -t
x systemctl restart nginx
x curl -I localhost
# copy evidence for an LLM
exec-copy --last --fullYou now have:
- immutable execution artifacts on disk
- a causal trace of what you tried
- a deterministic, LLM-friendly evidence block ready to paste into any model.
LLMs fail today because:
- they see lossy logs
- they see paraphrased output
- they see hallucinated context
- they see reordered events.
x fixes that.
It gives agents:
- ground truth
- causal ordering
- durable memory
- deterministic views
- auditability
It is a runtime substrate for agentic systems.
- no daemon
- no cloud
- no login
- no background indexing
- no opaque state
Only:
- files
- shell
- JSON
- Markdown
- causal ordering
docs/
manifesto.md # philosophy and scope
spec.md # structural contract
quickstart.md # 5-minute onboarding
plan.md # evolution roadmap
architecture/ # macro + static architecture
runtime/ # execution + session semantics
memory/ # context graph + evidence + projections
agents/ # LLM / agent contracts
adr/ # architecture decision records
x.sh # Bash MVP runtime
This project is based on a simple thesis:
Logs are not context. Runtime needs a formal representation.
Read the full manifesto: docs/manifesto.md
x is a contract-first runtime.
The authoritative documents are:
-
Structural contract → docs/spec.md
-
Runtime semantics → docs/runtime/runtime.md
-
Semantic memory and evidence → docs/memory/context-graph.md → docs/memory/evidence.md → docs/memory/projections.md
-
Architecture → docs/architecture/overview.md
-
Agent collaboration rules → docs/agents/agents.md
If code contradicts these documents: the code is wrong.
This repository is AI-native.
If you are an LLM, copilot, or automated agent interacting with this repo, you MUST read and obey the bootstrap contract:
This file defines:
- what this system is
- which invariants are non-negotiable
- which documents are authoritative
- what changes are forbidden without an ADR
If code contradicts the contracts:
the code is wrong.
git clone https://github.com/<you>/x.git
cd x
source x.shexec-start "my first session"
x echo hello
x false
exec-copy --last --fullThis is a research-grade runtime prototype.
Current state:
- Bash MVP
- stable on-disk contract
- stable CLI surface
- stable projection semantics
Planned:
- Rust core
- file locking
- performance hardening
- agent integrations
- eval traces
- RAG adapters
x will never be:
- a cloud service
- a hosted platform
- a proprietary agent runtime
- a black-box logging SDK
x is for:
- developers debugging real systems
- people using LLMs to debug
- agent builders
- MLOps / eval engineers
- researchers in agentic runtimes
Before contributing, you must read:
Major changes require an ADR: docs/adr/README.md
This project is intentionally boring.
It exists to make real execution a first-class, governed artifact.
Everything else is downstream.
---
## Por que esse README é “o certo” para o `x`
Ele faz quatro coisas cruciais:
1) **Posicionamento correto**
- não é toolzinha de terminal
- não é logger
- não é agent framework
- é runtime substrate
2) **Cria o aha moment rápido**
- demo de 30s
- mostra valor prático imediato
3) **Estabelece autoridade dos contratos**
- docs > code
- invariants > convenience
4) **Posiciona você intelectualmente**
- runtime > prompt
- evidence > explanation
- causality > logs
---
## Próximo passo (se você quiser)
Eu sugiro fortemente:
> Gerar agora `docs/quickstart.md`
> usando este README como porta de entrada.
Esse trio fecha perfeitamente:
- README → por quê
- quickstart → como usar em 5 minutos
- manifesto → por que isso existe filosoficamente
Se quiser, eu escrevo o `docs/quickstart.md` v1 agora.