akernel-runtime 0.1.4

Agent Kernel: a CLI-first context-native agent runtime prototype.

Context Kernel

Context Kernel is a CLI-first agent runtime for reducing prompt bloat, memory drift, and unnecessary token spending.

Most agent systems treat the prompt as the runtime. Context Kernel treats the prompt as a small working set assembled from structured state, scoped skill contracts, explicit policy checks, and measurable token budgets.

The project is currently an alpha CLI release. It is ready for local experimentation, benchmark-driven iteration, and early contributor feedback.

Naming

akernel means Agent Kernel. The project name is Context Kernel because the runtime focuses on context assembly, memory, policy, skills, and token budgets; the executable is akernel because users invoke the agent-facing kernel directly from the terminal.

The shorter kernel command is intentionally avoided because it is too broad and already carries strong meanings in operating systems, Jupyter, and other AI projects. akernel keeps the kernel idea while giving the CLI a distinct, searchable identity.

Package and command names map to the same idea:

• GitHub repository: context-kernel
• Python distribution: akernel-runtime
• Python import package: context_kernel
• CLI command: akernel
• npm launcher: @context-akernel/akernel

Why This Exists

Modern agent workflows often become expensive for reasons that are hard to see:

• large skill packs are loaded even when a task is simple
• long conversation history is repeatedly compressed and replayed
• memory is mixed with chat transcript instead of stored as typed state
• tool instructions and safety rules are duplicated across every call
• token regressions are noticed only after costs have already climbed

Context Kernel is an experiment in moving those responsibilities into a runtime layer that can be inspected, tested, and improved.

Core Capabilities

• Structured memory: typed records backed by local SQLite and JSONL state.
• Progressive skill contracts: load only the level of a skill that the task needs.
• Token budgets: estimate and report context pressure before provider calls.
• Resumable task planning: keep long work in structured milestones and compact checkpoints instead of replaying chat history.
• Bounded agent loop: support read_file, write_file, patch_file, batch_patch, run_command, and respond actions.
• Policy-gated tools: keep file and command execution behind explicit runtime checks.
• Traceability: write run traces, tool traces, compact agent reports, and token cost reports.
• Regression gates: compare evals and benchmarks, including behavior and token cost regressions.
• OpenAI-compatible provider: use project-local .env config with any compatible /v1 endpoint.

Architecture

request
  -> router
  -> budgeter
  -> memory retriever
  -> skill contract loader
  -> provider adapter
  -> verifier
  -> state writer
  -> trace and cost reports

The guiding rule is simple: every context inclusion should be explainable before the model runs, and every optimization should have a trace or benchmark behind it.

Install

Windows One-Command Setup

git clone <repository-url>
cd context-kernel
.\setup.cmd
akernel setup
akernel

setup.cmd creates .venv, installs the local CLI in editable mode, and prepares project-local .env if needed. wake.cmd activates the environment, loads .env, and prints common commands. The .cmd wrappers avoid local PowerShell execution-policy friction.

setup.cmd also installs user-level launchers in %USERPROFILE%\.akernel\bin and adds that directory to the user PATH. After opening a new terminal, akernel works from any directory, starts the interactive agent session by default, and uses that current directory as the workspace location. Environment lookup prefers the current project .env, then falls back to the installed Context Kernel project .env. akernel-chat remains as a compatibility shortcut.

Manual Python Install

python -m pip install -e .[dev]
akernel --help

Python 3.10 or newer is required.

PyPI Install

The Python runtime is published on PyPI as akernel-runtime:

python -m pip install --user akernel-runtime
akernel setup
akernel

GitHub Remote Install

Windows users can also install directly from GitHub:

irm https://raw.githubusercontent.com/huanxin0825-ctrl/context-akernel/main/scripts/install_remote.ps1 | iex
akernel setup
akernel

npm Launcher

The npm launcher is prepared for publication. After @context-akernel/akernel is published, it will provide a Node-style entrypoint and bootstrap the Python package if it is missing:

npm install -g @context-akernel/akernel
akernel setup
akernel

Set AKERNEL_PIP_SOURCE=git+https://github.com/huanxin0825-ctrl/context-akernel.git to make the npm launcher bootstrap from GitHub instead of PyPI.

Quick Start

akernel setup
akernel init . --scan
akernel
akernel --ui tui
akernel --provider mock

Inside the interactive session, type a task and press Enter. Bare akernel accepts chat flags such as --provider mock, --model, --aux-model, --max-steps, and --ui tui without requiring the explicit chat subcommand. --ui auto uses the full-screen terminal UI on real terminals and falls back to classic output for CI, pipes, and tests. akernel init . --scan or akernel project scan writes a compact .akernel/project.json profile with detected languages, package managers, key files, project instruction files such as AGENTS.md, and test/build commands; this profile enters future context packets without loading the whole repository. If you ask to run tests or verify without naming a command, the agent prefers the scanned project test command. If you ask it to fix failing tests, the agent can run that profile test command, inspect one or more failing files from the command output, apply a bounded patch or rollback-safe batch patch when the failure is simple enough, and rerun verification. Use /status for the live workspace view, /model for primary and auxiliary model roles, /cost for the last run's token report, /task to inspect the current task session, and /exit to leave. The shell UI renders a cockpit-style dashboard with a status header, command strip, transcript, mission panel, model stack, workspace summary, task progress, run timeline, diagnostics, and assistant responses. In --model-routing auto mode, low/medium first-step planning can run on the auxiliary model while high-risk, deep, warning-heavy, or synthesis steps stay on the primary model. In --aux-review auto mode, auxiliary review runs before primary-model steps and is included in token cost reports.

If you want to prepare the benchmark workspace manually:

akernel --workspace .sandbox skill register examples\skills\edit_file.json
akernel --workspace .sandbox skill register examples\skills\context_budget.json
akernel --workspace .sandbox memory add --kind preference --text "Prefer CLI-first context budget prototypes." --tags cli
akernel --workspace .sandbox plan "Plan a CLI context budget prototype"

Run the benchmark suite and gate it against the latest matching baseline:

akernel --workspace .sandbox bench run examples\benchmarks\phase2
akernel --workspace .sandbox bench gate examples\benchmarks\phase2 --require-baseline
akernel --workspace .sandbox bench run examples\benchmarks\scale
akernel --workspace .sandbox bench evidence --limit 3 --fail-under 30 --output .sandbox\benchmark-evidence.md

bench gate requires the current benchmark checks to pass, then compares behavior and token cost against a saved baseline. bench evidence turns saved benchmark reports into a Markdown proof page with total kernel tokens, baseline tokens, token savings, pass rate, strongest savings, and weakest savings. The current deterministic scale snapshot is documented in Benchmark Evidence.

OpenAI-Compatible Provider

Provider configuration is project-local. Copy .env.example to .env or use setup.cmd -ForceEnv.

AKERNEL_OPENAI_API_KEY=replace-with-your-key
AKERNEL_OPENAI_BASE_URL=https://clarmy.cloud/v1
AKERNEL_OPENAI_MODEL=gpt-5.5
AKERNEL_OPENAI_AUX_MODEL=gpt-5.3-codex

Legacy CONTEXT_KERNEL_OPENAI_* names are still read as a compatibility fallback, but new projects should use AKERNEL_OPENAI_*.

Useful checks:

akernel doctor
akernel models --provider openai
akernel --workspace .sandbox run "Reply with exactly OK." --provider openai --model gpt-5.5 --profile lean
akernel --workspace .sandbox run "Reply with exactly OK." --provider openai --model gpt-5.3-codex --profile lean

The base URL should include /v1.

CLI Highlights

akernel
akernel --workspace .sandbox chat
akernel context "Continue this task" --task <task-id> --resume
akernel task start "Ship a complex feature" --goal "Plan, implement, verify, and document the feature" --plan
akernel task next <task-id>
akernel task checkpoint <task-id> --milestone M1 --status completed --note "Investigation complete"
akernel project scan
akernel project show
akernel memory audit
akernel memory prune --max-records 100 --dry-run
akernel memory global-push
akernel memory global-pull --limit 20
akernel memory global-push --namespace team-runtime --tag shared --dry-run
akernel memory global-pull --namespace team-runtime --source-project my-project --dry-run
akernel skill market-list
akernel skill market-list --index examples\marketplace\skills\index.json
akernel skill market-install multi_file_bugfix
akernel skill market-install remote_skill --index https://example.com/context-kernel/skills/index.json --trust-remote
akernel compare "Summarize the project goal"
akernel eval run examples\evals\phase2.json
akernel eval cost <report-id>
akernel eval diff <before-id> <after-id> --fail-on-regression
akernel bench cost <report-id>
akernel bench diff <before-id> <after-id> --fail-on-regression
akernel bench evidence --limit 3 --fail-under 30 --output benchmark-evidence.md
akernel agent run "Patch notes/plan.txt and run tests" --provider openai --max-steps 4
akernel agent cost <agent-run-id>

Inside akernel, type a natural-language task and press Enter. Use /cost for the last run's token report, /task to inspect the current task session, and /exit to leave.

When an agent run cannot continue, the CLI prints a compact diagnostic with a category, reason, and suggested next step. Common categories include provider configuration, provider auth/network/protocol errors, context budget blocks, policy blocks, command failures, malformed provider actions, and loop guards.

See docs/03-cli-mvp.md for the full command surface.

Development

python -m pip install -e .[dev]
python -m unittest discover -s tests -p test_runtime.py
python -m build

The repository CI runs unit tests, package build checks, CLI smoke tests, benchmark regression gates, and the Windows setup/wake flow. See docs/07-release-and-ci.md.

Documentation

• Vision
• Architecture
• Execution Plan
• CLI MVP
• Evaluation Strategy
• Local Wake Workflow
• Skill Compiler
• Release And CI
• Open Source Plan
• Product Roadmap
• Benchmark Evidence
• Publishing Setup

Project Status

Context Kernel is alpha software. The CLI is functional, tested, and benchmarked locally, but the public API and file formats may still change as the runtime model matures.

Good first contribution areas:

• new eval fixtures for real coding and research workflows
• better routing and scoring strategies
• richer token cost visualization
• provider adapters for more OpenAI-compatible endpoints
• documentation improvements from fresh-user setup attempts

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, keep changes small and benchmarkable, and include tests for behavior that affects routing, budgeting, policy, tools, or reports.

Security

Do not commit .env, API keys, provider responses containing secrets, or local .akernel state. See SECURITY.md for reporting guidance.

License

Apache License 2.0. See LICENSE.