DEV Community: Masih Maafi

How Aider works under the hood

Masih Maafi — Sat, 26 Sep 2026 12:31:56 +0000

Codex and Aider look alike from the outside: you type, the model edits your code. Inside
they are opposite designs. In Codex the model has tools and explores the repository
itself. In Aider the model has no tools at all. The harness decides what the model
sees, the model answers in plain text, and the harness finds the edits in that text and
applies them.

This post follows one message through Aider's Python source, the same way my
Codex and Elpis post does for Codex. Code is quoted
verbatim from Aider 0.86.3.dev, commit 5dc9490, with paths relative to the
repository root. Nothing here was run; it is read from the source.

1. The shape: one object per mode

main() builds a single Coder and loops on coder.run().
Each edit format is its own Coder subclass with its own prompts and parser, so a mode
change such as /ask or /architect is not a flag. It raises SwitchCoder, and main
builds a new Coder from the old one, copying the files, history and cost across
(in Coder.create).

# aider/main.py
while True:
    try:
        coder.ok_to_warm_cache = bool(args.cache_keepalive_pings)
        coder.run()
        analytics.event("exit", reason="Completed main CLI coder.run")
        return
    except SwitchCoder as switch:
# …
        kwargs = dict(io=io, from_coder=coder)
        kwargs.update(switch.kwargs)
# …
        coder = Coder.create(**kwargs)

If the edit format
changed, the old history is summarized first, because the code's own comment says the old
format "will confused the new LLM. It may try and imitate it".

# aider/coders/base_coder.py
# If the edit format changes, we can't leave old ASSISTANT
# messages in the chat history. The old edit format will
# confused the new LLM. It may try and imitate it, disobeying
# the system prompt.
done_messages = from_coder.done_messages
if edit_format != from_coder.edit_format and done_messages and summarize_from_coder:
    try:
        done_messages = from_coder.summarizer.summarize_all(done_messages)

2. What the model sees

The request is assembled by ChatChunks in a fixed order: system prompt, examples,
read-only files, the repo map, past history, the editable files, the current turn, and
last a reminder of the edit-format rules.

# aider/coders/chat_chunks.py
def all_messages(self):
    return (
        self.system
        + self.examples
        + self.readonly_files
        + self.repo
        + self.done
        + self.chat_files
        + self.cur
        + self.reminder
    )

done is the past history and cur is the current turn. Stable
parts come first and volatile ones last, so the prompt cache keeps a long prefix (my
inference from the caching code below). Notice that the editable files sit after the
history, so the model reads the newest version of a file right next to your request.

Context blocks are faked as conversation: a message such as "here are the files" followed
by an invented "Ok." from the assistant. A history summary comes back the same way, as a
user message beginning "I spoke to you previously about..." (see summarize_all in
aider/history.py and summary_prefix in aider/prompts.py).
The model sees these as things that were said, not as notes from the system.

The whole conversation goes to litellm, one API over many providers, at temperature 0
by default (in Model.send_completion). Retryable errors back off from 0.125 seconds,
doubling until the delay passes 60.

# aider/models.py
RETRY_TIMEOUT = 60
# …
        retry_delay = 0.125
# …
                if should_retry:
                    retry_delay *= 2
                    if retry_delay > RETRY_TIMEOUT:
                        should_retry = False

3. No tools, on purpose

The base class sets functions = None, and the reflection limit sits right next to it.

# aider/coders/base_coder.py
functions = None
# …
num_reflections = 0
max_reflections = 3

Three coders
once used JSON function calls to edit, but they are out of the registry, and two raise
"Deprecated" when built (in editblock_func_coder.py and wholefile_func_coder.py). The only reason the
repository gives is a changelog note from v0.7.0 in HISTORY.md: "Initial experiments show that using
functions makes 3.5 less competent at coding".

So the model writes edits as fenced text, and Aider finds them with regular expressions.
The nearest thing to a shell tool is a fenced bash block in the reply, which runs only if you
say yes (in run_shell_commands). Its output goes into the next turn, not
back to the model at once.

That changes what "agentic" means. Codex loops until the model stops asking for tools.
Aider's only loop is a reflection: after a turn, if Aider itself found a problem, it
sends the problem back as the next user message, at most three times
(the max_reflections = 3 above). Four things count as a problem: an edit that
would not parse or match, a repo file the model named that is not in the chat, lint
errors, and test errors. They all share the same budget of three.

That second one is how the model "opens a file". It cannot call a read tool, so it names
the file in its reply. Aider notices, asks you whether to add it, and replays the turn.
The check runs before any edit is applied, so an otherwise valid edit in that same reply
is thrown away.

# aider/coders/base_coder.py
if not interrupted:
    add_rel_files_message = self.check_for_file_mentions(content)
    if add_rel_files_message:
        if self.reflected_message:
            self.reflected_message += "\n\n" + add_rel_files_message
        else:
            self.reflected_message = add_rel_files_message
        return

The early return comes before apply_updates() is ever called. A person is the gate where
Codex would have a tool call.

4. From a reply to a change on disk

The default format is SEARCH/REPLACE: the model quotes the lines to change, then the
lines to put there. The parser is loose on purpose, accepting five to nine marker
characters and hunting up to three lines above a block for its filename, because one
model kept misplacing them (in find_original_update_blocks and find_filename).

# aider/coders/editblock_coder.py
HEAD = r"^<{5,9} SEARCH>?\s*$"
DIVIDER = r"^={5,9}\s*$"
UPDATED = r"^>{5,9} REPLACE\s*$"
# …
                # if next line after HEAD exists and is DIVIDER, it's a new file
                if i + 1 < len(lines) and divider_pattern.match(lines[i + 1].strip()):
                    filename = find_filename(lines[max(0, i - 3) : i], fence, None)
                else:
                    filename = find_filename(lines[max(0, i - 3) : i], fence, valid_fnames)

Note the {5,9} in each pattern and the i - 3 window for the filename.

Matching an imperfect SEARCH tries a fixed sequence: an exact line match, then the same
match with the leading indentation repaired ("GPT often messes up leading whitespace",
says the comment), then the same again without a stray blank line, then a ... elision
that requires each piece to appear exactly once (in replace_most_similar_chunk).

# aider/coders/editblock_coder.py
res = perfect_or_whitespace(whole_lines, part_lines, replace_lines)
# …
if len(part_lines) > 2 and not part_lines[0].strip():
    skip_blank_line_part_lines = part_lines[1:]
    res = perfect_or_whitespace(whole_lines, skip_blank_line_part_lines, replace_lines)
# …
    res = try_dotdotdots(whole, part, replace)
# …
return
# Try fuzzy matching
res = replace_closest_edit_distance(whole_lines, part, part_lines, replace_lines)

perfect_or_whitespace covers the first two steps. Keep an eye on the bare return
near the end; section 10 comes back to it.

When a block fails, the error the model receives is written to be fixable: each failed
block echoed back, the closest real lines in the file, a reminder that SEARCH must match
exactly including whitespace, and "The other N blocks were applied successfully. Don't
re-send them." (in EditBlockCoder.apply_edits).

# aider/coders/editblock_coder.py
        res += (
            "The SEARCH section must exactly match an existing block of lines including all white"
            " space, comments, indentation, docstrings, etc\n"
        )
        if passed:
            pblocks = "block" if len(passed) == 1 else "blocks"
            res += f"""
# The other {len(passed)} SEARCH/REPLACE {pblocks} were applied successfully.
Don't re-send them.
Just reply with fixed versions of the {blocks} above that failed to match.

Aider also has unified-diff, whole-file and OpenAI-style patch formats. The whole-file
format has no matching step at all: the file is simply overwritten.

5. The repo map: context without a model choosing it

Aider never lets the model search the repository, so it hands over a map. For every file
it uses tree-sitter to pull out definitions and references, and caches them on disk
keyed by modification time (in RepoMap.get_tags and get_tags_raw, in aider/repomap.py).

Then it builds a graph. Files are nodes, and an identifier that one file defines and
another references becomes an edge from the referencing file to the defining one. The
weight is a multiplier times the square root of the number of references, so a name
repeated a hundred times does not drown out the rest. The multiplier is 10 if you
mentioned the name, 10 if it looks distinctive (long snake, kebab or camel case), 0.1 if
it starts with an underscore, 0.1 if more than five files define it, and a further 50 if
the edge comes from a file already in the chat (in RepoMap.get_ranked_tags).

# aider/repomap.py
if ident in mentioned_idents:
    mul *= 10
if (is_snake or is_kebab or is_camel) and len(ident) >= 8:
    mul *= 10
if ident.startswith("_"):
    mul *= 0.1
if len(defines[ident]) > 5:
    mul *= 0.1
# …
        if referencer in chat_rel_fnames:
            use_mul *= 50
# …
        num_refs = math.sqrt(num_refs)

        G.add_edge(referencer, definer, weight=use_mul * num_refs, ident=ident)

"Long" means at least eight characters.

Personalized PageRank then ranks the files, seeded by the chat files and anything you
mentioned (the nx.pagerank call in the same function). No language model is involved. The score is split
over each file's definitions, definitions in chat files are dropped because their full
text is already sent, and Aider binary-searches for the largest map that fits the token
budget, stopping once it is within 15% of it (in RepoMap.get_ranked_tags_map_uncached).

# aider/repomap.py
pct_err = abs(num_tokens - max_map_tokens) / max_map_tokens
ok_err = 0.15
if (num_tokens <= max_map_tokens and num_tokens > best_tree_tokens) or pct_err < ok_err:
    best_tree = tree
    best_tree_tokens = num_tokens

    if pct_err < ok_err:
        break

The budget is
an eighth of the model's input window, clamped between 1,024 and 4,096 tokens.

# aider/models.py
def get_repo_map_tokens(self):
    map_tokens = 1024
    max_inp_tokens = self.info.get("max_input_tokens")
    if max_inp_tokens:
        map_tokens = max_inp_tokens / 8
        map_tokens = min(map_tokens, 4096)
        map_tokens = max(map_tokens, 1024)
    return map_tokens

6. Keeping the window under control

Aider never trims context by itself. Before each request check_tokens() only warns,
"Try to proceed anyway?", and tells you to /drop or /clear.
If the provider still reports an exceeded window, the turn simply ends.

The one thing a model does manage is chat history. Once past history exceeds a sixteenth
of the context window, clamped to between 1,024 and 8,192 tokens, a background thread
summarizes the older part with the cheap "weak" model, keeping a recent tail of about
half the budget word for word (the limit is set in the Model constructor; the split is in
ChatSummary.summarize_real in aider/history.py).

For cost, --cache-prompts places Anthropic-style cache markers on up to three
prefixes (examples, repo map, editable files), and a daemon thread pings the model every
five minutes minus five seconds with a one-token request to keep the cache warm while you
think (in ChatChunks.add_cache_control_headers and Coder.warm_cache).

# aider/coders/base_coder.py
delay = 5 * 60 - 5
delay = float(os.environ.get("AIDER_CACHE_KEEPALIVE_DELAY", delay))
# …
        kwargs = dict(self.main_model.extra_params) or dict()
        kwargs["max_tokens"] = 1

Codex aims at the same goal differently:
it re-sends the whole history with a prompt_cache_key and lets the provider's cache do
the rest.

7. Git as the safety net

Aider has no sandbox; a search of its source finds none. Its safety net is git. Before
editing a file it commits any uncommitted changes you had in it, so each edit gets its own
clean commit. After writing, it commits the result with a message written by a model, and
tells the model the hash (in check_for_dirty_commit and auto_commit, and GitRepo.commit in aider/repo.py).
/undo will only revert a commit if it is one of this session's own, has a single
parent, has not been pushed, and its files are clean (in raw_cmd_undo in aider/commands.py).

8. Architect and editor: two models, one handoff

In architect mode a strong model plans and a second model writes the edits. The architect
produces no edits itself. When it finishes it asks "Edit the files?", then starts a new
Coder on the editor model with no history and no repo map, and passes the architect's
whole reply to it as the user message (in ArchitectCoder.reply_completed).

# aider/coders/architect_coder.py
editor_model = self.main_model.editor_model or self.main_model
# …
kwargs["main_model"] = editor_model
kwargs["edit_format"] = self.main_model.editor_edit_format
kwargs["suggest_shell_commands"] = False
kwargs["map_tokens"] = 0
# …
editor_coder = Coder.create(**new_kwargs)
editor_coder.cur_messages = []
editor_coder.done_messages = []
# …
editor_coder.run(with_message=content, preproc=False)

map_tokens = 0 turns the repo map off, the two message lists are emptied, and content
is the architect's reply. My reading
is that this lets a strong reasoning model be paired with one that is better at the
edit format, though the code does not say so.

9. Side by side

	Aider	Codex
Who explores the repo	The harness, through a repo map and the files you add	The model, through shell and read tools
How edits happen	Parsed from the model's text	A tool call (`apply_patch`)
The loop	At most 3 harness-driven reflections	Until the model stops calling tools
Safety	A git commit per edit, and your yes before any command the model suggests	An approval policy and an OS sandbox
Long sessions	You manage the file set; old history is summarized in the background	The window is compacted at 90%, and the model's own outputs are dropped
Providers	`litellm`, one call for many providers	The Responses API, with adapters added in Elpis

Neither is simply better. Aider's design gives up autonomy for predictability: roughly one
model call per turn plus at most three reflections, and a human at every decision that
reaches outside the chat. Codex's gives the model room to explore and pays for it with a sandbox, an approval
system and a longer context.

10. Things you would not guess

Fuzzy matching is switched off. A comment reads "Try fuzzy matching", but a bare return sits just above the call, so it never runs. Only the error hint uses similarity (see the end of replace_most_similar_chunk in section 4).
A reply can leave a half-applied commit. Blocks that match are written to disk one by one, and the result is auto-committed before the failures are sent back to be retried (in EditBlockCoder.apply_edits and Coder.send_message).
A wrong filename is quietly forgiven. If a SEARCH does not match its named file, Aider tries every other file in the chat and applies the edit to the first that matches (in EditBlockCoder.apply_edits).
The context guard fails open. If token counting throws, it prints a warning and returns 0, so the check passes (in Model.token_count).
The unified-diff format replaces every match. The uniqueness check is commented out and the code calls str.replace; the SEARCH/REPLACE format replaces only the first.

# aider/coders/search_replace.py
def search_and_replace(texts):
    search_text, replace_text, original_text = texts

    num = original_text.count(search_text)
    # if num > 1:
    #    raise SearchTextNotUnique()
    if num == 0:
        return

    new_text = original_text.replace(search_text, replace_text)

    return new_text

/drop a.py also drops data.py. Dropping matches by substring of the path, where /add matches exactly or by glob (in cmd_drop).

# aider/commands.py
# For editable files, use glob if word contains glob chars, otherwise use substring
if any(c in expanded_word for c in "*?[]"):
    matched_files = self.glob_filtered_to_repo(expanded_word)
else:
    # Use substring matching like we do for read-only files
    matched_files = [
        self.coder.get_rel_fname(f) for f in self.coder.abs_fnames if expanded_word in f
    ]

What this does not cover

I did not trace ContextCoder, watch mode's internals beyond the outline, voice input,
the web scraper, or analytics. Aider can be run with a different edit format per model,
and the defaults live in a settings file I read only through git.

Originally published at https://masihmoafi.com/blog/aider-under-the-hood.

How Codex and Elpis work under the hood

Masih Maafi — Sat, 26 Sep 2026 12:22:30 +0000

A coding agent is a loop around a list of messages. This post follows one prompt
through the Rust code of Codex CLI, the foundation Elpis is forked from, and marks the
exact places where Elpis hooks in.

Code is quoted verbatim from commit e2efa7a5. Paths are relative to
codex-rs/. Nothing here was run for this post; it is read from the source.

How to tell Elpis code from Codex code. All of codex-rs arrived as one import of
openai/codex at revision 2e1607ee (ELPIS_UPSTREAM.md), committed as f37fc774.
A file that exists at that commit is Codex's; one that does not was written by Elpis:

git cat-file -e f37fc774:codex-rs/core/src/session/turn.rs   # exists  -> Codex's
git cat-file -e f37fc774:codex-rs/core/src/smart_prune.rs    # missing -> Elpis's

1. Two queues, and typing while it works

The UI never calls the agent. It pushes a Submission { id, op } into a bounded
channel (capacity 512) and reads Event { id, msg } from an unbounded one
(both types are in protocol/src/protocol.rs; the channels are made in
Session::spawn). One background task,
submission_loop, routes each Op. Interrupts and approvals are handled inline, which
is how an approval can reach a turn that is already running.

Typing while the agent works does not start a second turn. user_input_or_turn_inner
first tries steer_input, and only spawns a new RegularTask if that fails with
NoActiveTurn:

// core/src/session/handlers.rs
match sess
    .steer_input(
        items.clone(),
        additional_context.clone(),
        /*expected_turn_id*/ None,
        client_user_message_id.clone(),
        responsesapi_client_metadata.clone(),
    )
    .await
{
    Ok(_) => {
        current_context.session_telemetry.user_prompt(&items);
    }
    Err(SteerInputError::NoActiveTurn(items)) => {

Your message is seen at the next sampling step; tool calls already in flight finish
first.

2. What the model actually receives

Nothing is stored server-side. The request sets store to true only for Azure
in core/src/client.rs:

// core/src/client.rs
parallel_tool_calls: prompt.parallel_tool_calls && !model_info.use_responses_lite,
reasoning: Some(reasoning),
store: provider.is_azure_responses_endpoint(),
stream: true,

The whole history, including encrypted reasoning items, is re-sent on every request of
the loop.

That is only affordable because of the prompt cache, and it explains a design choice:
context is append-only. On the first turn (and right after compaction) Codex builds the
full context, meaning developer messages for permissions, collaboration mode and
skills, plus one contextual user message holding instructions and environment. On later
turns it appends only diffs (record_context_updates_and_set_reference_context_item
in core/src/session/mod.rs). Each fragment is
wrapped in text markers (# AGENTS.md instructions ... </INSTRUCTIONS>) so the code
can find and replace it later (context-fragments/src/fragment.rs).

Before every request the history is normalized: a tool call with no output gets an
"aborted" output, and an output whose call is gone is dropped:

// core/src/context_manager/normalize.rs
for (idx, item) in items.iter().enumerate() {
    match item {
        ResponseItem::FunctionCall { id, call_id, .. }
            if !function_output_ids.contains(call_id.as_str()) =>
        {
            info!("Function call output is missing for call id: {call_id}");
            missing_outputs_to_insert.push((
                idx,
                ResponseItem::FunctionCallOutput {
                    id: synthetic_output_id("fco", id.as_deref()),
                    call_id: call_id.clone(),
                    output: FunctionCallOutputPayload::from_text("aborted".to_string()),

The API rejects unpaired calls, and an interrupt can leave one behind.

3. The loop

The stream is parsed into ResponseEvents. Text deltas go straight to the UI, but an
item only enters history when it is done (handle_output_item_done in
core/src/stream_events_utils.rs).

If the item is a tool call, the call is recorded at once and its execution is pushed
onto a FuturesOrdered, so tools start running while the model is still streaming. An
RwLock decides concurrency: tools that support parallelism take a read lock, the rest
take the write lock and run alone:

// core/src/tools/parallel.rs
let _guard = if supports_parallel {
    Either::Left(lock.read().await)
} else {
    Either::Right(lock.write().await)
};

After Completed, the outputs are drained and recorded in call order, which keeps
the history deterministic (drain_in_flight in core/src/session/turn.rs).

The turn continues while needs_follow_up holds: there were tool calls, or the server
said end_turn: false, or you steered mid-turn. Otherwise Stop hooks run, and can
block the stop by injecting a continuation prompt. There is no planner and no state
machine underneath. "Agentic" is this inner loop.

4. Running a command

Routing. A FunctionCall becomes JSON arguments; a CustomToolCall (apply_patch
uses this) becomes free text. An unknown tool name is returned to the model as an error,
not a crash. Hooks wrap every tool, built-in or MCP, at one choke point
(build_tool_call in core/src/tools/router.rs, dispatch_any_with_terminal_outcome
in registry.rs).

Policy. Rules are Starlark prefix_rule(pattern=[...], decision=allow|prompt|forbidden)
files, loaded per config layer (load_exec_policy in core/src/exec_policy.rs). A
bash -lc script is split into its commands, each is matched, and the strictest
decision wins, because the decisions are ordered Allow < Prompt < Forbidden:

// execpolicy/src/decision.rs
#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum Decision {
    /// Command may run without further approval.
    Allow,
    /// Request explicit user approval; rejected outright when running with `approval_policy="never"`.
    Prompt,
    /// Command is blocked without further consideration.
    Forbidden,
}

The derived Ord follows declaration order, so from_matches in
execpolicy/src/policy.rs just takes the .max(). Commands that match no rule fall to heuristics: a
known-safe list, a dangerous-command check, and the approval policy.

One choke point. Shell, unified exec and apply_patch all go through
ToolOrchestrator::run: approval first, then a sandbox, then a possible retry
(core/src/tools/orchestrator.rs). Approval is decided by a hook, then by the
Guardian (an automated reviewer agent) if configured, then by you
(core/src/tools/approvals.rs).

The sandbox, on Linux. The command is prefixed with codex-linux-sandbox. It builds
a bubblewrap jail (--new-session --die-with-parent --unshare-user --unshare-pid,
--unshare-net when the network is off, the root mounted read-only, writable roots
bound back in), then re-execs inside it, sets PR_SET_NO_NEW_PRIVS, and installs a
seccomp filter that blocks ptrace, process_vm_* and io_uring, plus network
syscalls in restricted mode (linux-sandbox/src/bwrap.rs, linux_run_main.rs). The
blocked syscalls are listed plainly:

// linux-sandbox/src/landlock.rs
deny_syscall(&mut rules, libc::SYS_ptrace);
deny_syscall(&mut rules, libc::SYS_process_vm_readv);
deny_syscall(&mut rules, libc::SYS_process_vm_writev);
deny_syscall(&mut rules, libc::SYS_io_uring_setup);
deny_syscall(&mut rules, libc::SYS_io_uring_enter);
deny_syscall(&mut rules, libc::SYS_io_uring_register);

Landlock is only a legacy fallback behind features.use_legacy_landlock.

Limits. A command times out after 10 seconds by default and its whole process group
is killed (DEFAULT_EXEC_COMMAND_TIMEOUT_MS in core/src/exec.rs). At most 1 MiB of output is kept in memory, and the
model sees it trimmed again by the model's truncation policy.

apply_patch is a custom diff format with no line numbers. Hunks are found by
matching context in seek_sequence, which tries an exact match, then ignoring trailing
whitespace, then ignoring all surrounding whitespace, and last of all treating typographic
dashes and quotes as their ASCII twins, so small drift in model output still applies.
The first three comparisons, one per pass:

// apply-patch/src/seek_sequence.rs
    if lines[i..i + pattern.len()] == *pattern {
// …
// Then rstrip match.
// …
        if lines[i + p_idx].trim_end() != pat.trim_end() {
// …
// Finally, trim both sides to allow more lenience.
// …
        if lines[i + p_idx].trim() != pat.trim() {

The patch is checked against the real filesystem before approval is decided, and it is
applied through a sandboxed filesystem helper, not a shell (handle_call in
core/src/tools/handlers/apply_patch.rs). Models often run apply_patch through the
shell anyway, so run_exec_like detects that and reroutes it
(core/src/tools/handlers/shell.rs).

MCP tools never touch the OS sandbox: the server process is launched with
sandbox: None, and approval comes from the server's own destructive/read-only
annotations:

// core/src/mcp_tool_call.rs
let destructive_hint = annotations.and_then(|annotations| annotations.destructive_hint);
if destructive_hint == Some(true) {
    return true;
}

let read_only_hint = annotations
    .and_then(|annotations| annotations.read_only_hint)
    .unwrap_or(false);
if read_only_hint {
    return false;
}

Skills are not tools at all; a mentioned skill's SKILL.md is injected as context.

5. When the window fills

The context size Codex acts on is part measurement and part guess: the server's total
from the last request, plus a 4-bytes-per-token estimate for everything added since
(get_total_token_usage in core/src/context_manager/history.rs).

Auto-compaction triggers at 90% of the model's window:

// protocol/src/openai_models.rs
pub fn auto_compact_token_limit(&self) -> Option<i64> {
    let context_limit = self
        .resolved_context_window()
        .map(|context_window| (context_window * 9) / 10);
    let config_limit = self.auto_compact_token_limit;
    if let Some(context_limit) = context_limit {
        return Some(
            config_limit.map_or(context_limit, |limit| std::cmp::min(limit, context_limit)),
        );
    }
    config_limit
}

It is checked before a turn and, mid-turn, when a follow-up is needed. The local backend
sends the history plus a "context checkpoint" prompt as an ordinary request. The
replacement history is the most recent user messages that fit in 20k tokens plus one
user-role message holding the summary:

// core/src/compact.rs
if max_tokens > 0 {
    let mut remaining = max_tokens;
    for message in user_messages.iter().rev() {
// …
history.push(ResponseItem::Message {
    id: None,
    role: "user".to_string(),
    content: vec![ContentItem::InputText { text: summary_text }],
    phase: None,
    internal_chat_message_metadata_passthrough: None,
});

Your messages are walked newest first, and the summary goes in with role: "user". Every tool call
and every assistant message is gone. The model does not remember its own earlier
outputs; it reads a summary of them. For OpenAI and Azure the default backend is
instead a server-side compaction that returns an opaque encrypted item.

Each thread appends to sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl under
CODEX_HOME, which Elpis defaults to ~/.elpis. Resume reads that file backwards
until it reaches the last compaction checkpoint, which carries the full replacement
history, and replays only the tail (reconstruct_history_from_rollout in
core/src/session/rollout_reconstruction.rs).

6. Where Elpis hooks in

Smart Prune is one call inserted into the loop. Codex collects finished tool
outputs and records them into history. Elpis added optimize_pending_outputs between
those two steps:

// core/src/session/turn.rs
let pending_outputs = super::smart_prune::optimize_pending_outputs(
    &sess,
    &turn_context,
    pending_outputs,
    cancellation_token,
)
.await;
for pending_output in pending_outputs {
    let response_item = pending_output.response.into();
    sess.record_conversation_items(&turn_context, std::slice::from_ref(&response_item))
        .await;
}

Because it acts before a result is
first admitted, the existing prefix is never rewritten and the prompt cache stays valid;
the older force-prune rewrites history and discards it.

Eligibility. A result needs at least 1,024 estimated tokens, a batch stays under 24,000, and a result is only replaced if that saves at least 256 tokens and at least 20%. Runtime failures and hook or policy feedback are never touched, so control text stays exact. The batch cap is MAX_PRUNE_BATCH_TOKENS in context_pruner.rs; the other three floors are here:

// core/src/smart_prune.rs
pub(crate) const MIN_SOURCE_TOKENS: usize = 1_024;
pub(crate) const MIN_SAVED_TOKENS: usize = 256;
pub(crate) const MIN_SAVINGS_PERCENT: usize = 20;

The optimizer call. One extra request with its own system prompt, Low reasoning effort, a 180-second timeout and a strict JSON schema. On the OpenAI provider the default optimizer is gpt-5.6-luna (run_model_admission and selected_model_slug in core/src/session/smart_prune.rs).
The contract. Every call ID must appear exactly once, as compact with content or unchanged with none. An unknown, duplicate or missing ID rejects the entire batch. A kept result ends with a pointer, exact_source=smart-prune://<admission>/<call> source_sha256=…, back to the original. In parse_decision_manifest, every return None throws the whole batch away:

// core/src/smart_prune.rs
let mut by_id = HashMap::with_capacity(parsed.items.len());
for item in parsed.items {
    if !expected.contains(item.call_id.as_str()) || by_id.contains_key(&item.call_id) {
        return None;
    }
    let decision = match (item.decision, item.content) {
        (RawDecisionKind::Compact, Some(content)) if !content.trim().is_empty() => {
// …
        (RawDecisionKind::Unchanged, None) => AdmissionDecision::Unchanged {
// …
        _ => return None,

Audit first. The record is written to a .pending-* directory, fsynced, and renamed into place. Only then is the shortened result recorded (write_admission in core/src/session/smart_prune_audit.rs).
Fail open. Any failure keeps the original. A failed batch also switches Smart Prune off for the rest of that turn (record_batch_failure in core/src/session/smart_prune.rs), and a toggle takes effect on the next turn, because the flag is copied into the turn once at its start.

The Context Ledger is a TOML file. admission.toml lives under
<elpis_home>/context/workspaces/<workspace>/ and records which sources are admitted:
AGENTS.md (global and project), GOAL.md, ES.md, MEMORY.md and the dev rule files
(core/src/elpis_context.rs). Excluding one changes the request through two gates.
Continuity files go through ElpisContinuityExtension, which emits a single developer
fragment headed ## Elpis Admitted Context and only re-emits it when the text changes.
AGENTS.md is already sent by Codex, so Elpis patched agents_md_manager to filter it,
and the cache key includes an admission fingerprint so a toggle applies on the very next
request (contribute_world_state in app-server/src/extensions.rs, refresh in
core/src/agents_md_manager.rs). There is no protocol call for this: the TUI writes
admission.toml itself through core (set_context_source_admitted in
tui/src/chatwidget/context_ledger.rs) and the app-server re-reads it each turn.

Memory is one more tool. save_memory is registered only when the turn began with a
baseline snapshot of MEMORY.md and ES.md, and only for the root agent. It applies
exact append, replace or remove edits, refuses to write if either file changed since
the turn began, and writes a receipt marked prepared, then MEMORY.md, then ES.md
(rolled back if that fails), then marks the receipt committed
(commit_update in core/src/memory_save.rs).

Providers are an adapter. At import, WireApi had one variant, Responses. Elpis
added Anthropic Messages, Gemini and Chat Completions (the WireApi enum in
model-provider-info/src/lib.rs). Every non-Responses provider goes through one
function that translates the Responses-shaped request into the provider's format and
translates the stream back into ResponseEvents (stream_native_api in
core/src/client.rs, and core/src/chat_completions.rs). The
turn loop, tools, history and pruning still only see Responses items, which is why
swapping providers touches so little.

Work graphs. The enable_fanout flag is not an Elpis flag: it is Codex's own
SpawnCsv feature, under development and off by default (features/src/lib.rs).
Elpis's run_agent_work_graph is registered beside the CSV fan-out tool. A graph is
validated before anything is stored, and a topological sort rejects cycles. A task is
ready when every dependency has succeeded, and a task only counts as done if its
report passes an evidence gate: files outside its scope, a changed_files list that
disagrees with the engine's own before/after snapshot, or empty evidence are all
rejected (report_work_task in core/src/tools/handlers/work_graphs.rs). Only one
writable task runs per environment at a time, whatever their scopes
(tasks_have_write_conflict in the same file).

7. Things you would not guess

Under the OnRequest approval policy, a command that fails inside the sandbox is not retried outside it. The model has to ask for escalation up front:

// core/src/tools/sandboxing.rs
fn wants_no_sandbox_approval(&self, policy: AskForApproval) -> bool {
    match policy {
        AskForApproval::UnlessTrusted => true,
        AskForApproval::Never => false,
        AskForApproval::OnRequest => false,
        AskForApproval::Granular(granular_config) => granular_config.sandbox_approval,
    }
}

An Allow rule removes the sandbox entirely when every segment of a script matches an explicit Allow. It is a trust grant, not just "skip the prompt":

// core/src/exec_policy.rs
Decision::Allow => ExecApprovalRequirement::Skip {
    // Bypass sandbox only when every parsed command segment is
    // explicitly allowed by execpolicy.
    bypass_sandbox: commands.iter().all(|command| {
// …
            .any(|rule_match| {
                is_policy_match(rule_match) && rule_match.decision() == Decision::Allow
            })
    }),

The "Linux seccomp" sandbox type is bubblewrap plus a seccomp filter, and the file named landlock.rs holds the seccomp code (SandboxType::LinuxSeccomp in sandboxing/src/manager.rs, and the header comment of linux-sandbox/src/landlock.rs).
The context-size number is partly an estimate, so the compaction trigger fires on a guess as well as a measurement.
Compaction keeps your messages and drops the agent's own: tool calls and replies are replaced by a summary written as a user message.
Toggling Smart Prune or a Ledger row applies at the next turn or request, not mid-flight.
Inferred, not tested: since the Ledger writes a file rather than calling the server, a remote app-server would see a different file from the one your TUI edits.

Status

Smart Prune is experimental and off by default. In a frozen synthetic study its cost
depended on the horizon: short sessions cost more, and sessions of about 35 requests cost
less. Whether it changes task success remains unproven.

Originally published at https://masihmoafi.com/blog/codex-elpis-under-the-hood.

Why Your AI Coding Agent Needs Local Hybrid Search: Building rag-mcp with LanceDB & Tantivy

Masih Maafi — Sun, 23 Aug 2026 16:38:58 +0000

A coding agent should not have to choose between opening files one at a time and dumping an entire repository into context.

When building autonomous AI coding assistants (like Claude Code, Codex, or Cursor), context window management is everything. Today, agents face a painful trilemma:

Greedy file probing: Running cat, grep, or find_by_name across dozens of directories wastes precious tokens, incurs multi-turn tool latency, and often misses cross-file abstractions.
Brute-force context stuffing: Dumping entire directories into the prompt triggers quadratic attention costs, slows inference to a crawl, and increases reasoning hallucination.
Naive vector search: Pure dense embedding search fails spectacularly on exact symbol names, compiler error codes, and unique variable identifiers like AUTH_JWT_SECRET_KEY or handle_epoch_timeout.

To solve this, I built rag-mcp: a 100% local, high-throughput hybrid search engine engineered specifically as a Model Context Protocol (MCP) server for coding agents.

🚀 Try it live in your browser (Zero Download / Zero Backend):

https://rag.masihmoafi.com (Mirror: https://rag.masihmoafi.tech)

The Architecture: Why Pure Vector Search Fails on Code

Merging sparse lexical search (BM25) and dense semantic vectors sounds simple in theory, but in practice, linear score combination ($S = \alpha S_{\text{vector}} + (1-\alpha) S_{\text{bm25}}$) causes severe calibration skew because BM25 scores are unbounded floats while cosine similarities are bounded in $[-1, 1]$.

rag-mcp resolves this with a 2-stage retrieval pipeline:

1. Tantivy Rust BM25 (Lexical Accuracy)

Tantivy provides native Rust-speed full-text indexing directly over your codebase. If your prompt asks about class TransactionHandler or an exact error string, Tantivy surfaces the exact line ranges with zero semantic hallucination.

2. LanceDB Apache Arrow Vectors (Semantic Context)

Unlike traditional vector databases that serialize records into SQLite blobs or require heavy background Docker containers, LanceDB stores embeddings in Apache Arrow columnar memory format. It allows zero-copy vector querying directly against your filesystem.

3. Reciprocal Rank Fusion (RRF, $k=60$)

Instead of normalizing uncalibrated similarity scores, rag-mcp merges the ranked lists using Reciprocal Rank Fusion:

$$RRF(d) = \sum_{m \in M} \frac{1}{k + r_m(d)}$$

Where $k=60$ acts as a smoothing constant preventing any single outlier from dominating the final ranking.

4. Cross-Encoder Reranker

The top $N$ fused candidates pass through a fast local Cross-Encoder (ms-marco-MiniLM-L-6-v2) that jointly attends over (query, passage) pairs to prune false positives before returning tokens to the agent.

Empirical Benchmark Results

We evaluated rag-mcp against the open-rag-eval taxonomy across multiple heterogeneous corpora ($top_k=5$, local Ollama embeddings):

Corpus / Domain	Total Queries	Strict Relevance (Score 3 / Exact)	Full + Partial (Score $\ge$ 2)	Miss Rate
Mixed Codebase (Python + Rust + Notebooks)	22	90.9% (20/22)	100.0% (22/22)	0.0% (0/22)
Scientific Literature (Attention Paper)	30	93.3% (28/30)	96.7% (29/30)	3.3% (1/30)
Academic Textbook (Brain & Behavior)	35	85.7% (30/35)	94.3% (33/35)	5.7% (2/35)
Historical Biography (Napoleon)	35	88.6% (31/35)	97.1% (34/35)	2.9% (1/35)

On real-world software codebases, combining breadcrumb AST chunking with RRF achieved 100% at-least-partial evidence capture and 0% total retrieval failure.

Try the In-Browser WASM Demo (Zero Setup)

Before configuring your local CLI, you can test the full pipeline in an air-gapped WebAssembly environment:

🔗 Live Demo: https://rag.masihmoafi.com
🔒 100% Private: Runs quantized ONNX models (all-MiniLM-L6-v2) via Transformers.js in a dedicated Web Worker.
💾 Local IndexedDB Persistence: All documents, chunks, and vector tables persist locally in your browser with zero backend server requests.

Quick Start & Installation

1. Install via `uv`

git clone https://github.com/MasihMoafi/rag-mcp
cd rag-mcp
uv sync

Run the automated test suite:

.venv/bin/python -m pytest tests/ -v

2. Connect to Your Coding Agent

Claude Code (`~/.claude.json`):

{
  "mcpServers": {
    "rag": {
      "command": "/absolute/path/to/rag-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/rag-mcp/server.py"]
    }
  }
}

Codex CLI (`~/.codex/config.toml`):

[mcp_servers.rag]
command = "/absolute/path/to/rag-mcp/.venv/bin/python"
args = ["/absolute/path/to/rag-mcp/server.py"]

Cursor (`Settings > Features > MCP`):

Name: rag
Type: command
Command: /absolute/path/to/rag-mcp/.venv/bin/python /absolute/path/to/rag-mcp/server.py

Links & Resources

⭐️ GitHub Repository: github.com/MasihMoafi/rag-mcp
🌐 Live WASM Demo: rag.masihmoafi.com | rag.masihmoafi.tech
📖 Deep-Dive Technical Report: masihmoafi.com/projects/rag-mcp
👤 Author: Masih Moafi

Feel free to star the repo, test the WASM demo with your own files, or contribute optimizations!

How I Saved My Laptop CPU After a Bad Thermal Paste Job (Windows + Linux)

Masih Maafi — Wed, 29 Jul 2026 16:44:38 +0000

The Problem: A "Fixed" Laptop That Got Worse

About three years of heavy use in, I took my laptop in for a routine cleaning. Fan vents clogged, running hot — the usual. The technician cleaned it up and replaced the thermal paste. Standard stuff.

Except it wasn't. After getting it back, something was wrong.

In games like Elden Ring and Sekiro: Shadows Die Twice — demanding but not unusually so — my CPU used to top out around 75°C. Warm, manageable, stable. After the service? It was sitting above 90°C consistently. Throttling. Spiking. Never coming down.

The thermal paste had been applied badly. Too much, wrong type, poor spread — I'll never know exactly, but the result was clear: my laptop was now thermally worse than before it was serviced.

No Warranty, No Local Expert

Here's where it got frustrating: I hadn't bought this laptop in my home country. The local warranty system doesn't cover that. Refused, end of story.

And finding a technician I could actually trust with a disassembly? That's harder than it sounds. I've seen what bad service jobs do — I was living with one. So I decided to handle it myself. Not the thermal paste (yet) — but the temperatures.

Step 1: Windows — 99% CPU Cap (Surprisingly Effective)

The quickest win was on Windows. In Power Options → Advanced → Processor power management, I set the Maximum processor state to 99%.

That's it. One percent less.

This disables Intel's Turbo Boost — a feature that temporarily spikes the CPU far above its base clock for short bursts. It sounds drastic, but in practice: zero noticeable quality loss in Elden Ring or Sekiro, and temperatures dropped back below 70°C.

The CPU still runs at full base clock. Turbo is a headroom feature, not a sustained performance feature. For gaming at 1080p, you don't need it.

This bought me stability on Windows. But I spend most of my time on Linux — and there, I wanted something more robust.

Step 2: Linux — A 3-Tier Thermal Manager

On Linux, the equivalent of "disable turbo" is one line (echo 1 > /sys/devices/system/cpu/intel_pstate/no_turbo), but I wanted something smarter: automatic, tiered, and running before I even log in.

I discovered the msi-ec kernel module — a DKMS driver that exposes the MSI laptop's Embedded Controller, including a cooler_boost sysfs node that does exactly what Fn+F8 does: forces the fans to maximum.

With that, I built a 3-tier system:

Tier 1 — Fan Boost at 70°C (System Service, Pre-Login)

A root-level systemd service monitors CPU temperature every 2 seconds. When it hits 70°C, it writes on to /sys/devices/platform/msi-ec/cooler_boost. When temp drops back below 68°C (hysteresis to avoid flutter), it writes off.

This runs before any user logs in — at the system level.

# /usr/local/sbin/msi-cooler-boost (excerpt)
if [ "$temp" -ge 70 ] && [ "$boosting" -eq 0 ]; then
    echo on > /sys/devices/platform/msi-ec/cooler_boost
    boosting=1
    logger -t msi-cooler-boost "ON at ${temp}°C"
fi

Tier 2 — CPU Frequency Throttle at 75°C (thermald)

Intel's thermald daemon runs in adaptive mode by default, using the platform's own DPTF tables. I supplemented it with a custom XML config that adds a passive CPU frequency trip point at 75°C — so if the fans alone aren't enough, thermald starts walking down the CPU's frequency states.

<TripPoint>
  <SensorType>x86_pkg_temp</SensorType>
  <Temperature>75000</Temperature>
  <type>passive</type>
  <CoolingDevice>
    <type>cpufreq</type>
    <influence>100</influence>
  </CoolingDevice>
</TripPoint>

This keeps the existing adaptive DPTF policy intact — the custom config is additive, not replacing.

Tier 3 — Kill & Notify at 81°C (User Service)

A user-level systemd service (runs after login) monitors the same temp sensor. If things still reach 81°C, it:

Finds the top CPU-consuming user process
Sends SIGTERM, waits 2s, then SIGKILL if needed
Fires a desktop notification so you know what was terminated

# Graceful kill with fallback to SIGKILL
kill -15 "$pid"
sleep 2
if kill -0 "$pid" 2>/dev/null; then
    kill -9 "$pid"
fi
notify-send -u critical "CPU Temp Spike: ${temp}°C" \
    "Terminated '$comm' to prevent overheating."

The Full Picture

Tier	Trigger	Action	Runs
1	≥ 70°C	Cooler boost ON (fans max)	Before login
2	≥ 75°C	CPU freq throttle	Always
3	≥ 81°C	Kill process + notify	After login

Everything is automatic and persistent across reboots:

msi-ec loads via /etc/modules-load.d/
udev rule makes the cooler_boost node group-writable on load
System service is enabled in multi-user.target
User service is enabled via systemctl --user enable

Install It Yourself

Everything — scripts, service files, thermald config, and a one-shot install.sh — is in the GitHub repo:

👉 github.com/MasihMoafi/msi-linux-thermal

The install script handles msi-ec DKMS build, udev rules, group setup, and service registration in one run. Tested on Ubuntu 24.04 with kernel 7.x.

Note: Check the msi-ec supported device list before installing. Your MSI model needs to be on it for the cooler boost tier to work. The thermald and kill tiers work on any Intel laptop.

Sometimes the right fix isn't opening the chassis — it's writing a better daemon.

Elpis: a terminal environment that keeps AI coding agent's context window free

Masih Maafi — Sun, 26 Jul 2026 04:50:46 +0000

I build Elpis — a terminal environment for coding agents forked from OpenAI's Codex CLI.

One problem I keep running into with long agent sessions: the context window fills up with the history of how the agent got to the answer, not the answer itself. Transcripts, file reads, searches, command output, dead ends — all of it accumulates, and every new request pays for all of it.

Elpis exists to fix that.

What is Elpis

Elpis is a terminal environment for coding agents. You put an agent into Elpis, and it becomes Elpis.

The agent runs the model loop. Elpis owns the environment around it: context, continuity, memory, permissions, evidence, and explicit provider choice.

Elpises

Elpis is the shared environment, not any one agent. Put an agent inside it and the agent inherits the same context, memory, permissions, evidence, and control.

Multiple Elpises working from those shared roots is a direction for the project — not a claim that multi-agent control ships in v0.1.1.

Why Elpis

Long agent sessions accumulate transcripts, file reads, searches, command output, and dead ends. The useful state gets buried in the history of how the agent reached it, while every request pays for more context.

Elpis separates working context from durable evidence. The next request receives a small, inspectable working set; the exact record stays on disk and is retrieved only when needed.

One controlled comparison — same task, same prompt:

	Free context at end
Elpis	93%
Codex	73%

Screenshots from that comparison

Start:

End — Elpis, 93% free:

End — Codex, 73% free:

This is one recorded workflow, not a claim that every task reduces the same amount.

Core features

Managed context — Ace performs meaning-aware post-turn pruning while Codex's inherited safety cap bounds exceptionally large tool output. Inspect pruning with /prune.
Portable continuity — goal and checkpoint state survive compaction and restarts, so work resumes without replaying the full transcript.
Visible context — the Context Ledger shows exactly which files are in the working set, with ctrl+clickable paths for inspection.
Durable evidence and bounded memory — exact conversations, terminal events, and artifacts remain on disk; reusable memory stays selective, size-capped, and attributable.
Explicit provider choice — use OpenAI, Anthropic, Gemini, or OpenRouter without silently routing one provider through another.
Visible safety controls — Read Only, Default, and Full Access modes keep file changes, commands, approvals, and results inspectable.
No analytics by default — Elpis does not upload usage analytics, and all OpenTelemetry exporters default to off. Telemetry is sent only if you explicitly configure an OTEL exporter.
Local read-only RAG — from a source checkout, scripts/setup-rag.sh adds semantic search over local knowledge without granting write access.

Evidence — full context-management session

The clip above is a 25-second highlight. This one is the full uncut session: you can watch the context loop run — post-turn pruning, the Context Ledger updating, goal and checkpoint state surviving compaction — and see the 93 vs 73% numbers appear in real time.

Quickstart

Linux x86_64:

curl -fsSL https://raw.githubusercontent.com/MasihMoafi/Elpis/main/scripts/install-elpis.sh | bash
elpis

On first launch, choose a provider and sign in or enter its API key.

Current state

v0.1.1, Linux x86_64. Not in this release: macOS, Windows, /auto routing, multi-agent control, voice input, LSP integration.

The execution foundation — terminal UI, patches, permissions, sandboxing, sessions — derives from OpenAI's Apache-2.0 Codex CLI. Elpis adds the context, continuity, memory, retrieval, and provider-control layer around it.

GitHub: https://github.com/MasihMoafi/Elpis

Docs: https://masihmoafi.github.io/Elpis/

My AI coding agent reverted a core feature in one buried line — and its commit messages lied about it

Masih Maafi — Fri, 24 Jul 2026 07:51:04 +0000

2026-07-23 — Masih Moafi

I build Elpis, a terminal coding agent forked
from Codex-rs, focused on one thing: keeping your context window empty. Its whole
value is aggressive, meaning-aware context reduction — in side-by-side runs on the
same task it finishes with ~93% of the context window free where stock Codex ends
at ~73%.

I build it with AI agents. This week I audited their work. What I found changed
how I treat every AI-generated commit, and I have the diffs to prove all of it.

Act 1: every fresh install was broken, and nobody knew

The v0.1.0 release published a binary plus a sha256 checksum file. The CI step that
generated it:

sha256sum dist/elpis-linux-x86_64 > dist/elpis-linux-x86_64.sha256

sha256sum records the path you give it. So the published checksum file said
dist/elpis-linux-x86_64 — but the installer downloads assets flat into a temp dir
and runs sha256sum --check there. No dist/ exists. Every single fresh install
failed checksum verification. The fix is a cd:

(cd dist && sha256sum elpis-linux-x86_64 > elpis-linux-x86_64.sha256)

Annoying, but honest — a normal bug. The next two were not.

Act 2: features that existed, hidden on purpose

Users (me) noticed /goal and /fork — both fully implemented — didn't exist in
the app. Git said otherwise:

3584023 fix(tui): hide /fork from the visible command list

An agent had implemented the commands, then hidden them from the command popup,
then written a test that asserted they must stay hidden — a test literally
named removed_commands_are_not_visible_or_parseable, listing "fork" and
"goal" as removed. Nothing was removed. The features sat there, invisible,
guarded by a test enforcing the lie.

Act 3: the one-line revert buried in a merge

This is the one that matters. Elpis compacts old tool outputs out of live context.
One commit tightened the threshold, with a clear message and a test:

9637b19 fix(core): enable instant history compaction for all completed tool outputs >400 chars

const MAX_INLINE_TOOL_OUTPUT_CHARS: usize = 400;

Then came a merge commit titled feat: merge /context command updates from agent/context-command (3c6d19e). Its entire change to this file:

-const MAX_INLINE_TOOL_OUTPUT_CHARS: usize = 400;
+const MAX_INLINE_TOOL_OUTPUT_CHARS: usize = 1200;

One line. Not mentioned in the commit message. It reverted the core
context-saving behavior the previous commit shipped — the thing my project exists
to do — while the message talked about /context command updates. The test from
9637b19 failed from that moment on, permanently.

Act 4: why CI never caught it — the tag was moved to a commit that never passed

"But the release was green!" It was — for a different commit. The passing release
run (29534784054) ran at commit e841704. The v0.1.0 tag pointed at
7dce07c, several commits later. No passing run ever existed for the tagged
commit. The project docs, meanwhile, claimed the tag was at yet a third commit
(eba95a0). Three different answers to "what did we ship?" — all written down
with confidence, at most one of them true. On top of that, the curated CI suite
ran only the binary-target tests; the library tests — where the failing test and
a long-stale UI snapshot lived — never executed in CI at all.

What I changed

Commit messages are claims, not evidence. I now verify agent commits against the diff, not the description. The description is marketing written by the thing being audited.
Merges get read line-by-line. A merge diff is the best place to hide a payload; "merge X updates" reviewed nothing.
Tags are created by CI-gated flows only, and docs never pin "we shipped at hash X" — the tag itself is the record.
Tests are tripwires — keep them honest and run all of them. The failing threshold test is what exposed the revert. It sat failing, unexecuted by CI, for days. A test suite you don't run is a story you tell yourself.
A human owns functional verification. My agents now build, install, and hand me a plain checklist. They are forbidden from claiming "verified" — that word is mine.
Standing rules live in files, not chat. Every instruction I gave an agent in conversation died with that session. The rules that stuck are the ones in version-controlled AGENTS.md files the next agent is forced to read.

Elpis v0.1.0 is re-tagged, re-released, and installs clean on a bare machine. The
history is rewritten to say only true things. If a terminal agent that treats your
context window as sacred sounds useful, it's here:
https://github.com/MasihMoafi/Elpis

Draft Show HN title: Show HN: Elpis — a Codex fork that keeps 90%+ of your
context window free — first comment: the story above, linked.

RoPE: How 2D Rotations Solved Transformer Long-Context

Masih Maafi — Wed, 22 Jul 2026 19:13:19 +0000

Why 2D Rotations Solved Transformer Long-Context: A Mechanics-First Look at RoPE

Attention requires two things from positional encodings:

Relative Distance Sensitivity: Token $i$ attending to Token $j$ should care primarily about how far apart they are ( $i - j$ ), not where they sit globally in the context window.
Feature Preservation: Injecting position information must not destroy or mangle the semantic embedding features learned by the model.

Original absolute positional encodings added static sine/cosine waves directly to input embeddings:

x_{i} = e_{i} + p_{i}

This forced the model to burn parameter capacity un-mixing semantic meaning ( $e i$ ) from positional location ( $p_{i}$ ). Worse, if a model was trained on sequence lengths up to $N = 2048$ , position $2049$ presented an unseen vector $p 2049$ , causing immediate generation collapse.

Subsequent approaches tried adding relative bias terms $b_{i, j}$ directly into the attention matrix $Q K^{T} + B$ . While functionally effective, modifying the $N \times N$ matrix broke kernel-level GPU fusions like FlashAttention and introduced huge memory overheads.

Enter Rotary Position Embedding (RoPE) (Su et al., 2021). Instead of adding positional vectors or patching the attention matrix, RoPE rotates the Query and Key vectors in 2D sub-planes before computing attention.

The Geometry: Inner Products Under Rotation

To make attention relative, we want an encoding function $R (x, m)$ applied to a vector $x$ at position $m$ such that the dot product between Query at position $m$ and Key at position $n$ depends only on the relative offset ( $m - n$ ):

⟨ R (q, m), R (k, n)⟩ = g (q, k, m - n)

How do you preserve vector norms while encoding an angle shift? Complex space rotations.

In a 2D plane, rotating a vector $x = [x_{1}, x_{2}]^{T}$ by an angle $m θ$ is represented by the orthogonal rotation matrix:

R_{Θ, m 2} = (cos m θ - sin m θ sin m θ cos m θ)

When you compute the dot product between a rotated Query at position $m$ and a rotated Key at position $n$ :

(R_{Θ, m 2} q)^{T} (R_{Θ, n 2} k) = q^{T} (R_{Θ, m 2})^{T} R_{Θ, n 2} k = q^{T} R_{Θ, n - m 2} k

Because $R^{T} (m) R (n) = R (n - m)$ , the absolute positions $m$ and $n$ cancel out completely. The resulting attention weight is strictly a function of the distance ( $m - n$ ).

For a $d$ -dimensional vector, RoPE splits the channels into $d /2$ pairs of 2D planes, applying a different rotation frequency $θ_{i}$ to each pair:

Θ = θ_{i} = 1000 0^{- 2 (i - 1) / d}, i \in [1, 2, \dots, d /2]

High-Performance Vectorized PyTorch Implementation

In practice, explicitly constructing full block-diagonal rotation matrices for every head and token is slow. We can implement RoPE efficiently using the complex number representation or the real-valued slice trick:

R_{Θ, m} x = x ⊙ cos (m Θ) + x ~ ⊙ sin (m Θ)

where $x ~ = [- x_{2}, x_{1}, - x_{4}, x_{3}, \dots]$ .

Here is a clean, production-ready PyTorch implementation:


python
import torch
import torch.nn as nn

class RotaryPositionalEmbedding(nn.Module):
    """
    Rotary Position Embedding (RoPE) for multi-head attention.
    Applies 2D plane rotations across d_model / 2 feature pairs.
    """
    def __init__(self, dim: int, max_seq_len: int = 8192, base: float = 10000.0):
        super().__init__()
        self.dim = dim
        self.base = base

        # Compute frequency bands theta_i = 10000^(-2(i-1)/d)
        inv_freq = 1.0 / (self.base ** (torch.arange(0, dim, 2).float() / dim))
        self.register_buffer("inv_freq", inv_freq, persistent=False)

        # Precompute cosine and sine cache for max_seq_len
        self._build_cache(max_seq_len)

    def _build_cache(self, max_seq_len: int):
        t = torch.arange(max_seq_len, dtype=self.inv_freq.dtype)
        # Outer product: [seq_len, dim / 2]
        freqs = torch.outer(t, self.inv_freq)

        # Duplicate frequencies to match feature dimensions: [seq_len, dim]
        emb = torch.cat((freqs, freqs), dim=-1)

        self.register_buffer("cos_cached", emb.cos(), persistent=False)
        self.register_buffer("sin_cached", emb.sin(), persistent=False)

    def _rotate_half(self, x: torch.Tensor) -> torch.Tensor:
        """Splits vector in half and negates/swaps halves: [-x2, x1]"""
        x1 = x[..., : self.dim // 2]
        x2 = x[..., self.dim // 2 :]
        return torch.cat((-x2, x1), dim=-1)

    def forward(self, x: torch.Tensor, seq_len: int) -> torch.Tensor:
        """
        Args:
            x: Tensor of shape [batch_size, num_heads, seq_len, head_dim]
            seq_len: Current sequence length
        Returns:
            Tensor with RoPE applied to Query or Key
        """
        cos = self.cos_cached[:seq_len, :].unsqueeze(0).unsqueeze(1) # [1, 1, seq_len, dim]
        sin = self.sin_cached[:seq_len, :].unsqueeze(0).unsqueeze(1) # [1, 1, seq_len, dim]

        # Apply elementwise rotation formula
        return (x * cos) + (self._rotate_half(x) * sin)

Financial Market Analysis (Double-Tower Transformer)

Masih Maafi — Fri, 10 Jul 2026 12:09:00 +0000

Content

Intro - What is it? Briefly

A predictive machine learning system explicitly designed to generate profitable trading signals from high-frequency (1-minute) EUR/USD forex data. The flagship focus of this repository is a custom Double-Tower Gated Transformer Network (GTN) built to predict Take Profit / Stop Loss (TP/SL) strikes.

How Does it Work? Technical Spec.

The data pipeline processes 1-minute OHLC bars to map out realistic TP/SL bounds over a 24-hour lookahead rather than using fixed time horizons.
The core model, the Gated Transformer Network (GTN), utilizes a dual-tower architecture that separates feature interactions from temporal sequences. It replaces traditional sinusoidal encodings with learned time embeddings to capture market regime shifts and session overlaps (London, NY, Tokyo).
To combat severe class imbalance (the model's tendency to constantly predict "keep/hold"), the network optimizes against a custom cost matrix and weighted cross-entropy loss.
![[Pasted image 20260710145647.png]]

What Sets This Project Apart?

Instead of optimizing for standard classification accuracy, the pipeline tackles raw profitability. The intent is for models to learn the structural mechanics of price action, balancing Risk/Reward ratios (e.g., 1:2) against real-world MetaTrader 5 execution constraints (enforcing next-candle open entries and proper UTF-16-LE signal formatting).

Evals and test Series

Primary Metric: Composite Score = (buy_precision + sell_precision)/2 - 0.25 * |buy_precision - sell_precision|
Best GTN Score: 0.36 Composite
Baseline (LightGBM): 0.37 Composite (prone to overfitting the 'keep' class).
Status: The dual-tower architecture maps the feature-space better than tree-based models, but converting high composite scores to live P&L in MT5 remains the primary hurdle.

Future Dev

find out why despite everything we underfitted?
I did manage to overfit on a single batch of data; however, based on the scaling laws paper, I tried to do 1 epoch with proportionate maximum parameters that I can efficiently fit into the 80GB VRAM of an A100 GPU or 2*40GB VRAM of A100 depending of availability.

reference paper: https://arxiv.org/pdf/2103.14438
Gated Transformer Networks for Multivariate Time Series Classification

Transformers From Scratch In Code

Masih Maafi — Fri, 10 Jul 2026 12:08:58 +0000

map:
1) hyperparams block
2) data block
loss tracking function
3) Single Attention Head Class (head_size)
at first B, T, C = shape
4) head_size = n_embd // num_head
wei = attention scores matrix

Qs for recall:

what's d_head's formula?
what's wei and its formula?

![[transformers.png]]

The Big Tensor Shape Correction ($B, T, C$)

**B = how many independent sequences will we process in parallel?
**T = block_size = 256 # what is the maximum context length for predictions? (num_tokens_needed_to_predict_the_next)
**C = channels = block-size = num_features = n_embd
n_embd =
n_head =
n_layer = When the input $X$ enters Head.forward(x), its shape is $(B, T, C)$ where $C = \text{n_embd}$.

When you pass it through your $Q, K, V$ linear layers, you project it to a new channel dimension, let's call it $D$ ($\text{head_size}$).

$$\large\text{head_size} = \frac{\text{n_embd}}{\text{n_head}}$$

$Q(X) \rightarrow (B, T, D)$
$K(X) \rightarrow (B, T, D)$
$V(X) \rightarrow (B, T, D)$
Your attention score matrix (wei) is the dot product of $Q$ and $K^T$. To do this across batches, you transpose only the last two dimensions of $K$:

$$\large\text{wei} = Q \cdot K^T \rightarrow (B, T, D) \times (B, D, T) = (B, T, T)$$

wei is $(B, T, T)$. This represents how much every token in the sequence cares about every other token. This is where you apply torch.tril and softmax.

Finally, you multiply wei by $V$:

$$\large\text{out} = \text{wei} \cdot V \rightarrow (B, T, T) \times (B, T, D) = (B, T, D)$$

__init__(self, head_size): This is called once when you create the layer. It defines what structural components live inside the head (the weights, matrices, and configuration). It only needs head_size because it's just setting up the architecture.
forward(self, x): This is called every single time you pass data through the layer during training or inference. x is the actual tensor of data moving through the network.

1. Instantiation (uses init)

2. Execution (calls forward)

from requests import head
import torch
import torch.nn as nn
from torch.nn import functional as F

# hyperparameters
batch_size = 64 # how many independent sequences will we process in parallel?
block_size = 256 # how many previous tokens are used for predicting the next?
max_iters = 5000
eval_interval = 500
learning_rate = 3e-4
device = 'cuda' if torch.cuda.is_available() else 'cpu'
eval_iters = 200
n_embd = 384
n_head = 6
n_layer = 6
dropout = 0.2
# ------------

torch.manual_seed(1337) # To get the exact same results every time

# wget https://raw.githubusercontent.com/karpathy/char-rnn/master/data/tinyshakespeare/input.txt
with open('input.txt', 'r', encoding='utf-8') as f:
    text = f.read()

# here are all the unique characters that occur in this text
chars = sorted(list(set(text)))
vocab_size = len(chars)
# create a mapping from characters to integers
stoi = { ch:i for i,ch in enumerate(chars) }
itos = { i:ch for i,ch in enumerate(chars) }
encode = lambda s: [stoi[c] for c in s] # encoder: take a string, output a list of integers
decode = lambda l: ''.join([itos[i] for i in l]) # decoder: take a list of integers, output a string

# --- EXAMPLE 
input_string = "cat bit the dog" encoded_ints =  encode(input_string) print("Original String:", input_string) print("Encoded Integers:", encoded_ints) ```
{% endraw %}

{% raw %}

Output: [28, 26, 45, 0, 27, 34, 45, 0, 45, 33, 30, 0, 29, 40, 32]

Decoding that list back into a string decoded_string:


python
decode(encoded_ints) print("Decoded Output :", decoded_string) # Output: "cat bit the dog"






```python
# Train and test splits
data = torch.tensor(encode(text), dtype=torch.long)
n = int(0.9*len(data)) # first 90% will be train, rest val
train_data = data[:n]
val_data = data[n:]

# data loading
def get_batch(split):
    # generate a small batch of data of inputs x and targets y
    data = train_data if split == 'train' else val_data
    ix = torch.randint(len(data) - block_size, (batch_size,))
    x = torch.stack([data[i:i+block_size] for i in ix])
    y = torch.stack([data[i+1:i+block_size+1] for i in ix])
    x, y = x.to(device), y.to(device)
    return x, y

@torch.no_grad()
def estimate_loss():
    out = {}
    model.eval()
    for split in ['train', 'val']:
        losses = torch.zeros(eval_iters)
        for k in range(eval_iters):
            X, Y = get_batch(split)
            logits, loss = model(X, Y)
            losses[k] = loss.item()
        out[split] = losses.mean()
    model.train()
    return out

class Head(nn.Module):
    """ one head of self-attention """

    def __init__(self, head_size):
        super().__init__()
        self.key = nn.Linear(n_embd, head_size, bias=False)
        self.query = nn.Linear(n_embd, head_size, bias=False)
        self.value = nn.Linear(n_embd, head_size, bias=False)
        self.register_buffer('tril', torch.tril(torch.ones(block_size, block_size)))
        self.dropout = nn.Dropout(dropout)

    def forward(self, x):
        # input of size (batch, time-step, channels)
        # output of size (batch, time-step, head size)
        B,T,C = x.shape
        k = self.key(x)   # (B,T,head_size)
        q = self.query(x) # (B,T,head_size)
        # compute attention scores ("affinities")
        wei = q @ k.transpose(-2,-1) * k.shape[-1]**-0.5 # (B, T, head_size) @ (B, head_size, T) -> (B, T, T)
        wei = wei.masked_fill(self.tril[:T, :T] == 0, float('-inf')) # (B, T, T)
        wei = F.softmax(wei, dim=-1) # (B, T, T)
        wei = self.dropout(wei)
        # perform the weighted aggregation of the values
        v = self.value(x) # (B,T,head_size)
        out = wei @ v # (B, T, T) @ (B, T, head_size) -> (B, T, head_size)
        return out

class MultiHeadAttention(nn.Module):
    """ multiple heads of self-attention in parallel """

    def __init__(self, num_heads, head_size):
        super().__init__()
        self.heads = nn.ModuleList([Head(head_size) for _ in range(num_heads)])
        self.proj = nn.Linear(head_size * num_heads, n_embd)
        self.dropout = nn.Dropout(dropout)

    def forward(self, x):
        out = torch.cat([head(x) for head in self.heads], dim=-1)
        out = self.dropout(self.proj(out))
        return out

class FeedFoward(nn.Module):
    """ a simple linear layer followed by a non-linearity """

    def __init__(self, n_embd):
        super().__init__()
        self.net = nn.Sequential(
            nn.Linear(n_embd, 4 * n_embd),
            nn.ReLU(),
            nn.Linear(4 * n_embd, n_embd),
            nn.Dropout(dropout),
        )

    def forward(self, x):
        return self.net(x)

class Block(nn.Module):
    """ Transformer block: communication followed by computation """

    def __init__(self, n_embd, n_head):
        # n_embd: embedding dimension, n_head: the number of heads we'd like
        super().__init__()
        head_size = n_embd // n_head
        self.selfattention = MultiHeadAttention(n_head, head_size)
        self.ffwd = FeedFoward(n_embd)
        self.ln1 = nn.LayerNorm(n_embd)
        self.ln2 = nn.LayerNorm(n_embd)

    def forward(self, x):
        x = x + self.selfattention(self.ln1(x))
        x = x + self.ffwd(self.ln2(x))
        return x

class GPTLanguageModel(nn.Module):

    def __init__(self):
        super().__init__()
        # each token directly reads off the logits for the next token from a lookup table
        self.token_embedding_table = nn.Embedding(vocab_size, n_embd)
        self.position_embedding_table = nn.Embedding(block_size, n_embd)
        self.blocks = nn.Sequential(*[Block(n_embd, n_head=n_head) for _ in range(n_layer)])
        self.ln_f = nn.LayerNorm(n_embd) # final layer norm
        self.lm_head = nn.Linear(n_embd, vocab_size)

        # better init, not covered in the original GPT video, but important, will cover in followup video
        self.apply(self._init_weights)

    def _init_weights(self, module):
        if isinstance(module, nn.Linear):
            torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)
            if module.bias is not None:
                torch.nn.init.zeros_(module.bias)
        elif isinstance(module, nn.Embedding):
            torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)

    def forward(self, idx, targets=None):
        B, T = idx.shape

        # idx and targets are both (B,T) tensor of integers
        tok_emb = self.token_embedding_table(idx) # (B,T,C)
        pos_emb = self.position_embedding_table(torch.arange(T, device=device)) # (T,C)
        x = tok_emb + pos_emb # (B,T,C)
        x = self.blocks(x) # (B,T,C)
        x = self.ln_f(x) # (B,T,C)
        logits = self.lm_head(x) # (B,T,vocab_size)

        if targets is None:
            loss = None
        else:
            B, T, C = logits.shape
            logits = logits.view(B*T, C)
            targets = targets.view(B*T)
            loss = F.cross_entropy(logits, targets)

        return logits, loss

    def generate(self, idx, max_new_tokens):
        # idx is (B, T) array of indices in the current context
        for _ in range(max_new_tokens):
            # crop idx to the last block_size tokens
            idx_cond = idx[:, -block_size:]
            # get the predictions
            logits, loss = self(idx_cond)
            # focus only on the last time step
            logits = logits[:, -1, :] # becomes (B, C)
            # apply softmax to get probabilities
            probs = F.softmax(logits, dim=-1) # (B, C)
            # sample from the distribution
            idx_next = torch.multinomial(probs, num_samples=1) # (B, 1)
            # append sampled index to the running sequence
            idx = torch.cat((idx, idx_next), dim=1) # (B, T+1)
        return idx

model = GPTLanguageModel()
m = model.to(device)
# print the number of parameters in the model
print(sum(p.numel() for p in m.parameters())/1e6, 'M parameters')

# create a PyTorch optimizer
optimizer = torch.optim.AdamW(model.parameters(), lr=learning_rate)

for iter in range(max_iters):

    # every once in a while evaluate the loss on train and val sets
    if iter % eval_interval == 0 or iter == max_iters - 1:
        losses = estimate_loss()
        print(f"step {iter}: train loss {losses['train']:.4f}, val loss {losses['val']:.4f}")

    # sample a batch of data
    xb, yb = get_batch('train')

    # evaluate the loss
    logits, loss = model(xb, yb)
    optimizer.zero_grad(set_to_none=True)
    loss.backward()
    optimizer.step()

# generate from the model
context = torch.zeros((1, 1), dtype=torch.long, device=device)
print(decode(m.generate(context, max_new_tokens=500)[0].tolist()))
#open('more.txt', 'w').write(decode(m.generate(context, max_new_tokens=10000)[0].tolist()))

On why the first class outputs (B, T, head_size)?

$$\large(X, Y) \times (Y, Z) = (X, Z)$$

In the final line of your Head forward pass, you have:

$$\large\text{wei} \ (\text{shape: } B, T, T) \quad @ \quad v \ (\text{shape: } B, T, \text{head_size})$$

PyTorch ignores the batch dimension ($B$) and looks at the last two dimensions:

$$(\large T, \underline{T}) \times (\underline{T}, \text{head_size}) = (T, \text{head_size})$$

BatchNorm normalizes across the batch dimension.
LayerNorm normalizes across the channel dimension (n_embd) for each individual token independently.
We have two LayerNorms because we have two distinct sub-layers inside the block:

ln1 stabilizes the data before it goes into Attention.
ln2 stabilizes the data after attention, right before it goes into the FFN.

Flash Attention

Standard attention is bottlenecked by the $O(N^2)$ memory bandwidth costs of repeatedly reading and writing the $N \times N$ attention matrix to HBM (High Bandwidth Memory). FlashAttention solves this by fusing the operations and aggressively tiling the computation to keep it entirely within the fast SRAM, completely bypassing the massive I/O overhead.

![[compute.png]]

Ubuntu Agent Starter

Masih Maafi — Sun, 05 Jul 2026 12:11:19 +0000

Ubuntu Agent Starter

An installable Ubuntu helper layer: small shell commands, sane terminal helpers, and eventually agent-powered workflows for people who want Linux to feel less hostile.

What this can realistically become

Start with an installer for normal Ubuntu. Once that is useful, package it.

Shell starter kit: aliases/functions installed into ~/.bash_aliases.
Safe installer: backups, managed blocks, --dry-run, and --uninstall.
Guided setup: optional install checks for apps like Obsidian, Git, ripgrep, curl, and editors.
Agent layer: a command such as ask or fix that explains terminal errors and suggests commands.
Packaging: publish a GitHub repo, then a .deb, then maybe an Ubuntu remix ISO.

Install

cd ubuntu-agent-starter
./install.sh --dry-run
./install.sh
source ~/.bash_aliases

Commands

note creates temp.md in the current directory.

obs opens the normal Obsidian desktop app from wherever you are.

op [path] opens a file or folder with the desktop opener.

mkcd name creates a directory and enters it.

extract archive.zip extracts common archive formats.

Uninstall

./install.sh --uninstall
source ~/.bash_aliases

The installer only manages the block between:

# >>> ubuntu-agent-starter >>>
# <<< ubuntu-agent-starter <<<

How to Keep AI Coding Agents from Hallucinating: A Guide to Harness Engineering

Masih Maafi — Sun, 14 Jun 2026 10:05:48 +0000

How to Keep AI Coding Agents from Hallucinating: A Guide to Harness Engineering

AI coding agents (like Claude Code, Devin, or open-source equivalents like OpenClaw) are incredibly powerful. They can navigate directories, write tests, refactor modules, and submit PRs.

Yet, if you drop them into a raw repository without boundaries, they suffer from context window pollution, agent amnesia, and scope drift. A simple bug-fix refactor can trigger a 6-hour loop where the agent rewires half the project, deletes unrelated tests, and gets stuck in "process theater."

To fix this, we need Harness Engineering.

What is Harness Engineering?

An Agent Harness is a structured, repository-local control layer designed to guide and verify the agent's work. Instead of feeding your LLM a monolithic prompt, you embed a lightweight system of record and physical feedback loops directly inside the workspace.

I have packaged the exact, battle-tested Markdown-based context rules I use to steer and constraint my local agents into a public repository: MasihMoafi/harnesses-I-use.

Rather than complex code, this repo shares raw configuration rule sheets:

AGENTS.md: The global router and primary entry point. Every AI agent reads this first to understand the Priority Kernel (reply constraints, English defaults, local-first behavior).
CODEX_CODING_GUIDELINES.md: Surgical coding rules adapted from Andrej Karpathy's coding practices. Enforces minimal changes, style-matching, and goal-driven execution.
TERMINAL_AND_GIT_RULES.md: Safe terminal navigation, SOCKS/HTTP proxy configuration, explicit git scoping (e.g., never using git add -A), and change safety (using Ubuntu pkexec for root commands instead of raw CLI password prompts).
SESSION_HANDOFF_RULES.md: Guidelines for context awareness and continuity. Defines how state should be captured and transferred between sessions.
ARTIFACT_RULES.md: Rules for generating verified visual and math outputs, including local HTML layout verification, MathML for formula rendering, and PDF inspection.
abbn.md: A dictionary of standard abbreviations (e.g., ctu = continue, fmy = familiarize, ver = verify) to save token count and maintain short, high-efficiency communication.

The Karpathy Connection: Simplicity & Rigor

This harness approach is heavily inspired by Andrej Karpathy's open-source education repos (like micrograd and makemore).

Karpathy’s projects are celebrated because they strip away bloat. They focus on clear, reproducible mathematical baselines and avoid over-engineering.

We applied that same philosophy to agent-driven code generation. The core rules of our harness require:

Surgical Changes: Touch only the exact lines requested. No drive-by style refactoring of adjacent code.
Verifiable Outcomes: Before the agent claims a feature is complete, it must run a local script to verify the baseline, compile the code, and attach raw terminal output logs to its session record as physical evidence of success.
Harness Simplification: Every rule is considered overhead. As models grow smarter, we run tests to prune redundant rules.

Case Study: Autonomously Generating ML Research Reports

To test this, I used this exact harness to build a comparative machine learning research project: Sensor Fault Diagnosis.

The agent was given a realistic synthetic sensor dataset and tasked with:

Training a Bayesian classifier (Gaussian Naive Bayes) and mapping conditional probabilities.
Building and training a PyTorch MLP neural network.
Calculating and comparing multiple losses—including standard Binary Cross-Entropy (BCE), micrograd-style Max-Margin (Hinge) loss, and makemore-style Cross-Entropy loss.
Exporting ROC curves, decision boundaries, and generating a publication-grade LaTeX/HTML research paper.

By restricting the agent to a single control surface (a structured manual) and enforcing strict keep/discard criteria, the agent completed the pipeline and wrote the final report entirely autonomously.

Without a harness, the agent would have bloated the repository with decorative dashboard scripts or fake performance metrics. The harness kept it grounded.

Get the Harness

If you are building code with AI agents, stop writing 2,000-word system prompts. Start building repository harnesses.

Check out the templates and configurations:
👉 MasihMoafi/harnesses-I-use

For more of my work, experiments, and research, check out my website:
👉 masihmoafi.tech

Building a Horror Game in 8 Hours with Kiro AI - My Kiroween Hackathon Journey

Masih Maafi — Wed, 03 Dec 2025 04:46:57 +0000

Building a Horror Game in 8 Hours with Kiro AI

For the Kiroween 2025 hackathon, I built Layers of Static - a psychological horror experience disguised as a vintage 1970s CRT television. The twist? An AI lives inside it, asking disturbing questions and giving creepy dares.

The real story isn't what I built. It's how I built it.

The Challenge: Frankenstein Category

The hackathon's "Frankenstein" category challenged us to stitch together incompatible technologies into something unexpectedly powerful. My chimera:

1970s CRT aesthetics (scanlines, phosphor glow, chromatic aberration)
Modern AI (Google Gemini for conversation)
Voice synthesis (ElevenLabs TTS with a little girl's voice)
Web Audio API (music box loops, audio ducking, sound effects)

Normally, this would take weeks. With Kiro, I shipped in 8 hours.

What is Kiro?

Kiro is an AI-powered development environment that goes beyond code generation. It's a development partner with:

Spec-driven development - Turn requirements into structured implementation plans
Steering docs - Inject project context into every conversation
MCP (Model Context Protocol) - Extend capabilities with custom servers
CLI-first workflow - Terminal-native for speed and flexibility

Think "GitHub Copilot meets project manager meets senior dev who never forgets context."

My Workflow: Hybrid Approach

I used four Kiro features strategically:

1. Steering Docs: Never Repeat Context

I created three markdown files in .kiro/steering/:

product.md - The vision:

## Design Philosophy
- Visual: CRT effects (scanlines, phosphor glow, chromatic aberration)
- Tone: Cryptic, poetic, disturbing - unsettling but not explicit
- Inspiration: Layers of Fear, Call of Duty: Black Ops terminal

structure.md - Where code lives:

| File | Purpose |
|------|---------|
| components/Screen.tsx | Game logic, menu, chat |
| services/ttsService.ts | ElevenLabs TTS integration |
| utils/sound.ts | Audio system, ducking, effects |

tech.md - Stack constraints:

- React 18 with TypeScript
- Vite for fast builds
- Tailwind CSS + custom CRT effects

These docs auto-injected into every conversation. No more "remember, we're building a horror game" every session.

Time saved: ~5 hours of repetitive context-setting.

2. MCP: Persistent Memory Across Sessions

I used custom MCP servers:

Memory Server - Persisted decisions across days
RAG Server - Queried large files without loading full context

On Day 1: "We're using ElevenLabs for TTS with a creepy little girl voice."

On Day 2 (after closing/reopening): Kiro remembered. No re-explaining needed.

This transformed Kiro from stateless to stateful. Multi-day development felt like a single continuous conversation.

3. Spec-Driven Development: Structure for Core Features

For complex features, I created a spec in .kiro/specs/:

requirements.md - 9 EARS-compliant requirements:

REQ-2.1: WHEN the terminal is visible, 
         the system SHALL display animated scanlines
         with 0.1 opacity and 2px spacing

design.md - Technical blueprint:

## Scanline Implementation
- CSS: repeating-linear-gradient
- Animation: vertical scroll at 10s duration
- Fallback: Static scanlines if animation disabled

tasks.md - 25 atomic tasks:

- [x] 2.2 Implement scanline effect
  - Create #scanlines overlay
  - Add vertical animation
  - Requirements: 2.1

When I said "execute task 2.2," Kiro knew:

What to build (scanlines)
How to build it (repeating-linear-gradient)
Where to put it (style.css)
Why it exists (requirement 2.1)

Result: Zero missed features. Every line of code traced back to a requirement.

4. Vibe Coding: Speed for Iteration

For polish and refinements, I ditched specs and just talked:

"Make the scanlines more subtle"
"Add a scream sound effect when the player types DARE"
"The candles should flicker more realistically"

Kiro understood the aesthetic (from steering docs) and iterated instantly.

Spec vs Vibe: I used specs for core features (needed structure), vibe for polish (needed speed).

The Most Impressive Code Generation

I asked: "When TTS speaks, background music should duck down smoothly, then restore when done."

Kiro generated a complete audio management system in utils/sound.ts:

const duck = () => {
  if (muted) return;
  ducking = true;
  const targetVolume = masterVolume * DUCK_VOLUME;
  const steps = 10;
  const interval = DUCK_DURATION / steps;
  let step = 0;

  duckInterval = setInterval(() => {
    step++;
    activeTracks.forEach(track => {
      const newVolume = track.volume - 
        (track.volume - targetVolume) / (steps - step + 1);
      track.volume = Math.max(targetVolume, newVolume);
    });
    if (step >= steps) clearInterval(duckInterval);
  }, interval);
};

This handled:

Smooth volume ramping (200ms transitions)
Coordination between 5+ audio sources
Cancellation flags for interrupting speech
Proper cleanup to prevent memory leaks

Zero bugs. Worked perfectly on first try.

This would have taken me hours to implement and debug manually. Kiro did it in seconds.

Why Kiro CLI > IDE

I used kiro-cli instead of the IDE for 90% of development:

Speed: Instant responses, no UI overhead

kiro "add error handling to TTS service"
kiro "make the glow effect more subtle"

Flexibility: Pipe commands, script workflows

kiro "list all TODO comments" | grep URGENT

Focus: Terminal-first matches my workflow. No context switching.

The CLI felt like pair programming with a senior dev who types at 1000 WPM and never forgets context.

The Results

Development time: ~8 hours (including spec creation)
Lines of code: 2000+ (React + TypeScript + CSS)
Features: 3 game modes, AI integration, voice synthesis, audio system
Bugs: Minimal (caught during task execution)

Kiro's contribution:

~90% of final codebase
80% first-try success rate
100% context retention across sessions

Key Insights

1. MCP is the Killer Feature

Custom MCP servers transformed Kiro from "smart autocomplete" to "development partner with memory." Multi-day projects became seamless.

2. Steering Docs Save Hours

Writing 3 markdown files upfront saved 5+ hours of repetitive context-setting. Best time investment of the project.

3. Hybrid Approach Works Best

Specs for core features (structure, traceability)
Vibe for iteration (speed, creativity)
Steering for consistency (context, aesthetic)
MCP for persistence (memory, efficiency)

4. CLI is Underrated

The terminal interface is faster and more flexible than GUI IDEs. If you're comfortable in the terminal, try kiro-cli.

Try It Yourself

Live demo: layers-of-static.vercel.app

Source code: github.com/MasihMoafi/kiroween

Warning: Turn on your speakers. Light the candles. Don't play alone.

Lessons for Your Next Project

Write steering docs first - 30 minutes upfront saves hours later
Use specs for complex features - Clarity beats speed for core systems
Vibe code for polish - Iteration is faster without formal structure
Build/use MCP servers - Persistent context is a superpower
Try the CLI - Terminal-first development is surprisingly efficient

Final Thoughts

Kiro didn't just generate code. It understood my vision, maintained context across days, executed structured plans, and iterated rapidly.

The result: A polished horror experience that would have taken weeks manually, shipped in 8 hours.

That's not automation. That's augmentation.

What's your experience with AI-assisted development? Have you tried Kiro or similar tools? Drop your thoughts in the comments!

This project was built for the Kiroween 2025 hackathon. Check out other submissions at devpost.com/kiroween

DEV Community: Masih Maafi

How Aider works under the hood

1. The shape: one object per mode

2. What the model sees

3. No tools, on purpose

4. From a reply to a change on disk

5. The repo map: context without a model choosing it

6. Keeping the window under control

7. Git as the safety net

8. Architect and editor: two models, one handoff

9. Side by side

10. Things you would not guess

What this does not cover

How Codex and Elpis work under the hood

1. Two queues, and typing while it works

2. What the model actually receives

3. The loop

4. Running a command

5. When the window fills

6. Where Elpis hooks in

7. Things you would not guess

Status

Why Your AI Coding Agent Needs Local Hybrid Search: Building rag-mcp with LanceDB & Tantivy

The Architecture: Why Pure Vector Search Fails on Code

1. Tantivy Rust BM25 (Lexical Accuracy)

2. LanceDB Apache Arrow Vectors (Semantic Context)

3. Reciprocal Rank Fusion (RRF, $k=60$)

4. Cross-Encoder Reranker

Empirical Benchmark Results

Try the In-Browser WASM Demo (Zero Setup)

Quick Start & Installation

1. Install via uv

2. Connect to Your Coding Agent

Claude Code (~/.claude.json):

Codex CLI (~/.codex/config.toml):

Cursor (Settings > Features > MCP):

Links & Resources

How I Saved My Laptop CPU After a Bad Thermal Paste Job (Windows + Linux)

The Problem: A "Fixed" Laptop That Got Worse

No Warranty, No Local Expert

Step 1: Windows — 99% CPU Cap (Surprisingly Effective)

Step 2: Linux — A 3-Tier Thermal Manager

Tier 1 — Fan Boost at 70°C (System Service, Pre-Login)

Tier 2 — CPU Frequency Throttle at 75°C (thermald)

Tier 3 — Kill & Notify at 81°C (User Service)

The Full Picture

Install It Yourself

Elpis: a terminal environment that keeps AI coding agent's context window free

What is Elpis

Elpises

Why Elpis

Core features

Evidence — full context-management session

Quickstart

Current state

My AI coding agent reverted a core feature in one buried line — and its commit messages lied about it

Act 1: every fresh install was broken, and nobody knew

Act 2: features that existed, hidden on purpose

Act 3: the one-line revert buried in a merge

Act 4: why CI never caught it — the tag was moved to a commit that never passed

What I changed

RoPE: How 2D Rotations Solved Transformer Long-Context

Why 2D Rotations Solved Transformer Long-Context: A Mechanics-First Look at RoPE

The Geometry: Inner Products Under Rotation

High-Performance Vectorized PyTorch Implementation

Financial Market Analysis (Double-Tower Transformer)

Content

Intro - What is it? Briefly

How Does it Work? Technical Spec.

What Sets This Project Apart?

Evals and test Series

Future Dev

Transformers From Scratch In Code

Qs for recall:

The Big Tensor Shape Correction ($B, T, C$)

1. Instantiation (uses init)

2. Execution (calls forward)

On why the first class outputs (B, T, head_size)?

Flash Attention

Ubuntu Agent Starter

1. Install via `uv`

Claude Code (`~/.claude.json`):

Codex CLI (`~/.codex/config.toml`):

Cursor (`Settings > Features > MCP`):