@felan-ai/ext-context

Runtime-portable progressive loading of nested AGENTS.md and CLAUDE.md instructions for Felan sessions.

Agent Core loads instructions at the session cwd during composition. This extension discovers instructions below that cwd after the agent successfully reads a file or the user submits a decoded CLI @file block. It walks from the cwd toward the observed file, skips the cwd itself, and loads at most one instruction file per nested directory with this precedence:

1. AGENTS.md
2. CLAUDE.md

Loaded files are normalized and deduplicated for the session. They enter each subsequent model context as one hidden pi-progressive-context message. While the loaded instructions remain unchanged, that message stays at one stable context position and later conversation history appends after it. Discovering additional instructions or rebuilding context after compaction re-anchors the updated message once. A new session clears all discovered paths and the anchor.

All file access goes through the cwd-contained AgentRuntime. Missing or unreadable files are nonfatal, and directories already checked during the session are not retried. Runtime containment rejects lexical traversal and symlink escapes.

Use /progressive-context to show the nested instruction files loaded in the current session.

The extension registers concise static progressive-context capability guidance during initialization. Discovered nested instructions remain transient, stable-position session context and continue to update as relevant files are observed.

Trigger limitations

• Progressive context affects the model call after a file read or attachment.
• Images do not expose original filesystem paths through Pi input events.
• CLI @file blocks and successful structured read results are supported; shell commands that read files do not emit structured file-read events.

Attribution

This package adapts the MIT-licensed pi-progressive-context implementation. See NOTICE and LICENSE for source details.

Composition and package boundary

import contextExtension from '@felan-ai/ext-context';

const extension = contextExtension;

Agent Core owns the cwd-level instruction file. This extension owns only nested discovery, deduplication, hidden context delivery, and the inspection command; the host supplies the cwd-contained AgentRuntime. It requires a compatible @felan-ai/agent-core peer and does not load ambient project resources.

Development

Source: packages/ext-context in https://github.com/felan-ai/felan.

corepack enable
pnpm install --frozen-lockfile
pnpm --filter @felan-ai/ext-context build
pnpm --filter @felan-ai/ext-context type-check
pnpm --filter @felan-ai/ext-context test

Related documentation

• Context and memory
• Architecture
• Extension catalog