Navigation
/
Learn
Get startedTeaching kli Your Project
GuidesChoose and Switch ModelsConnect a ProviderAdd a Custom OpenAI-Compatible ProviderRun Commands and Eval LispPersist and Resume SessionsManage Long ConversationsInspect and Edit ContextSteer a Running TurnRestrict What kli Can DoWork in the TUIRun kli Headless or PipedSwitch and Customize ProfilesUpdate kliLog Observability Events
ConceptsThe Live ImageExtensions All the Way DownThe Agent LoopSessions as a TreeContext and the System PromptTools and Hashline EditsCapabilities and Fault BarriersSecurity Model and SandboxingProfilesModels, Providers, and Transports
Extend
Extend kliChoosing an AltitudePrompt TemplatesPrompt Template AnatomyWrite Your First Prompt TemplateUsing ArgumentsPrompt Template ExamplesSkillsSkill AnatomyWrite Your First SkillAuthoring and DiscoverySkill ExamplesLisp ExtensionsLisp Extension AnatomyWrite Your First Lisp ExtensionContribution KindsDefining a Contribution KindRecoding LiveLoading and Managing ExtensionsLisp Extension ExamplesSharing ExtensionsPublishing Extensions
Reference
CLI & InstallInstallationEnvironment VariablesReading the Docs
Commands, Tools & TUISlash CommandsToolsKeymapThemes
Settings & Filessettings.jsonconfig.jsonThe programs.kli ModuleCapabilitiesProfilesFiles and Paths
Models & ProvidersProviders and Transports
Copy page

Context and the System Prompt

On this page
On this page
The base promptProject context filesThe discovery walkOverriding the system promptThe 2 MiB capHow it stays currentRelated

kli assembles the system prompt from per-directory context files (AGENTS.md, CLAUDE.md) and two override files, rebuilt on each turn — so what the model knows is what you edit into those files, not what you re-explain in chat.

The system prompt is the standing instruction block at the top of every request, the part the model reads before your message. kli assembles it from three layers: a base prompt it ships with, your project context files, and two override files. This page is about where each layer comes from and how they combine.

The base prompt

kli builds a base system prompt for every session. It states the agent's identity (you are kli, an interactive coding assistant in a terminal), lists the tools currently registered on the running session, carries a few tool-agnostic guidelines, and reports the current date and working directory as authoritative environment facts. The tool list is read live from the session, so a tool added by an extension appears in the prompt without a restart.

This base is the starting point. The other layers extend it or replace it.

Project context files

kli discovers per-directory context files and renders them into a # Project Context section appended to the system prompt. Each discovered file appears under a ## <path> heading followed by its contents, so the model sees both the instructions and where they came from.

In any one directory, kli looks for these names in order and takes the first that exists:

  1. AGENTS.md
  2. AGENTS.MD
  3. CLAUDE.md
  4. CLAUDE.MD

One file wins per directory. An AGENTS.md next to a CLAUDE.md means the CLAUDE.md is not read for that directory.

The discovery walk

Discovery starts at the working directory kli is running in and walks up the directory tree, stopping at the repository root. A directory holding .git (whether a directory or a worktree file) is the root, and the walk includes it. Outside a git repository, the walk continues up the full ancestor chain.

The walk gives you layered instructions. A context file at the repository root states project-wide conventions; a context file in a subpackage states conventions for that subpackage; both reach the model when you work inside the subpackage. kli orders the rendered section outermost first, so the root file comes before the deeper one, and the closest file is read last. A file that the global config directory contributes (~/.config/kli/) comes first of all, ahead of the repository chain. Files are deduplicated by path, so a single file reached two ways appears once.

Overriding the system prompt

Two files change the base prompt directly rather than adding a section.

SYSTEM.md replaces the base prompt entirely. When kli finds it, the shipped identity-and-tools prompt is dropped and your file's contents take its place. The project context section still renders after it, so AGENTS.md and CLAUDE.md instructions remain in effect under a custom base.

APPEND_SYSTEM.md appends to the prompt. Its contents are added after the base (or after your SYSTEM.md, when both are present) and before the project context section. Use it to add standing instructions without discarding the identity and live tool list the base prompt carries.

kli reads these two override files from the project config directory <repo>/.kli/ first, then the global config directory ~/.config/kli/, and takes the first that has content. A blank or whitespace-only file is treated as absent, so an empty SYSTEM.md does not silently erase the base prompt.

The assembled order, top to bottom, is:

  1. the base prompt, or your SYSTEM.md in full when present
  2. APPEND_SYSTEM.md
  3. the # Project Context section from AGENTS.md / CLAUDE.md

The 2 MiB cap

kli reads a context or override file only when it is at most 2 MiB. A larger file is treated as absent: not truncated, not partially read, just skipped, and for context files the next candidate name in the directory is tried. The cap is a guard against a pathological file, a checked-in binary or a runaway log that happens to match a candidate name, not a budget on how much you can write. It sits at or beyond what a model can ingest in its context window, so a real instruction file does not approach it.

How it stays current

The system prompt is rebuilt from these files on each submission, not cached at startup. Editing an AGENTS.md or a SYSTEM.md while kli is running changes what the model reads on your next message; there is nothing to reload. Each rebuild first removes the append block and project context section it composed last time, then composes fresh ones, so neither stacks up across turns.

prevSessions as a TreeTools and Hashline Editsnext