The fix is obvious in theory: go back and learn the fundamentals properly. The hard part is doing it without spending two years on a degree or burning out on a curriculum that assumes you have nothing else going on.

I’ve been working through teachyourselfcs.com as my backbone. Here’s the plan I’ve laid out for myself and why I structured it this way.

The Curriculum

TYCS breaks CS into 9 subjects and gives you a primary book and video course for each. The order is a suggestion, not a law:

The book choices are deliberate. SICP isn’t just a programming book – it’s a book about how to think computationally. OSTEP is genuinely readable in a way most OS textbooks aren’t. DDIA is probably the most practically useful book on the list if you’re building anything that handles data at scale.

The target is 100-200 hours per subject. That’s not a sprint, it’s a multi-year project. The goal isn’t to finish – it’s to build genuine depth in each area, then keep revisiting.

The Problem I Had to Solve First

Standard study advice – “30 minutes every day” – doesn’t work for me. I have high activation energy to start anything. Once I’m in, momentum takes over and I’ll go for hours. But that first 15 minutes of friction is real and it kills sessions before they begin.

So the plan is ignition-focused rather than sustainment-focused:

• Sessions start with a 15-minute minimum, not a 2-hour block. The bar to start is low. Once started, I usually continue past it.
• Entry point is whatever subject feels most alive right now, not necessarily the next one in sequence. The order matters less than actually engaging.
• Each subject has a concrete project attached – something you build, not just something you read. The project gives momentum a direction.

The Newton iteration thing from the TYCS intro stuck with me: when you hit something you don’t understand, go back to the start of the section and re-read. Each pass gets you further. Don’t skip over confusion – re-enter it.

How I’m Ordering It

I’m starting with three subjects in parallel across the first phase rather than going strictly sequential:

Programming (SICP) – Chapters 1-3, doing every exercise. The exercises are the learning. Reading without doing is just moving your eyes across text. I’m supplementing with Exercism problems when I want something more applied.

Computer Architecture (CS:APP / Nand2Tetris) – Starting with Nand2Tetris projects 1-5 because they’re hands-on in a way that makes the abstractions stick. Build an ALU, then a CPU, then an assembler. By the time you reach CS:APP, you’ve already built the thing the book describes.

Distributed Systems (DDIA) – Running this in parallel because I’m already working in this space and the reading compounds immediately with real work. DDIA cover-to-cover, then 2-3 papers per week from the MIT DSG reading list. The project target is implementing a Raft consensus module.

Algorithms and Math for CS come after the first wave. The ML path runs alongside: Andrew Ng’s ML course after Algorithms, fast.ai after OS and Networking.

What I’m Not Doing

No video lectures unless I’m stuck. The TYCS authors are explicit that books are the primary medium and videos are optional supplements. I’ve defaulted to videos too many times in the past – they feel productive but the retention without active practice is low.

No skipping exercises to “get through” material faster. The only way through SICP is through the exercises. Same with Nand2Tetris. The projects aren’t extra credit, they’re the point.

No treating this as interview prep. The goal is actual understanding. Some of it will be useful in interviews, but that’s a side effect, not the frame.

I’ll track hours per subject and update this post as I go.

I have tried Notion. Tried Apple Notes. Tried dumping things in a text file. All of them eventually become a graveyard of notes I never revisit.

So I set up something different. This post is about the system – what it is, why it works, and the one thing that makes it actually stick.

The problem with most note-taking

Most people take notes the wrong way. They copy. They highlight. They summarize what they read. Then they file it somewhere and feel organized.

None of that is learning. None of it compounds.

When you copy a sentence from a textbook, you are transcribing, not thinking. The note exists but the understanding does not. Two weeks later the note is as foreign as the textbook was the first time.

The thing that actually builds knowledge is elaborative encoding – restating an idea in your own words, connecting it to something you already understand. This is not a productivity tip. It is how memory works. You encode new information by hooking it into existing mental models. No hooks, no retention.

A second brain should force you to do that. Most setups do not.

Two systems, one vault

The system I use is a hybrid of PARA and Zettelkasten. They solve different problems.

PARA (Projects, Areas, Resources, Archive) is for navigation. It answers “where do I put this?” and “where do I find that?” It is project-oriented, folder-based, practical. Good for builders.

Zettelkasten is for thinking. It answers “what do I actually know?” and “how does this connect to that?” It is idea-oriented, flat, link-based. Good for writers and researchers.

The mistake people make is picking one and ignoring the other. PARA without Zettelkasten gives you a well-organized filing cabinet you never think with. Zettelkasten without PARA gives you a beautiful graph of ideas with no place to track actual work.

The vault structure I landed on:

00-Inbox/          everything lands here first
Projects/          one subfolder per active project
Daily/             date-named daily notes
Notes/             Zettelkasten permanent notes (flat)
Learning/          STEM subjects, structured
Templates/         note templates
Archive/           completed projects, old notes

Projects and Daily are pure PARA. Notes is pure Zettelkasten. Learning is the interesting hybrid.

The three note types that matter

Zettelkasten has three kinds of notes, and most explanations of the system spend too much time on the taxonomy and not enough on why the types are different.

Fleeting notes are raw captures. They live in 00-Inbox. They are temporary by design – process them within a week or delete them. Zero friction at capture time. Do not organize, do not format, just dump it.

Concept notes live in Learning/. One concept per note, explained in your own words. Fixed structure: what it is in your words, the core intuition, a concrete example you can trace through, where you got confused, and how it connects to things you already know. That last field – where you got confused – is the most valuable part most people skip. Your confusions are where your understanding has gaps. Future you needs to know where those are.

Permanent notes live in Notes/. These are the ones that compound. One fully-formed idea per note, stated as a claim. Not a topic – a claim.

BAD: Eigenvalues GOOD: Eigenvalues represent stretch magnitude along a transformation's invariant axes

BAD: CNCFlow GTM GOOD: CAD users switch tools only when workflow pain exceeds switching cost

The difference matters. A topic title is a filing label. A claim title is a thought. When you write it as a claim, you have to commit to believing something. That forces the thinking.

The rule that makes everything work

Write in your own words only. No copy-pasting.

This sounds obvious. It is the hardest part. The temptation when reading a paper or watching a lecture is to quote the good parts, paste them into a note, and feel like you captured something. You did not. You moved text from one place to another.

A wrong note you wrote yourself is more valuable than a correct note you copied. When you write something wrong, you will notice the contradiction when you link it to something else. The note will tell you where your understanding broke. A copied note just sits there looking authoritative.

Learning STEM in the vault

STEM is where this system earns its keep more than anywhere else.

The standard study loop – read, highlight, review – fails because it is passive. You are reading the author’s thoughts, not building your own. By the third session you are highlighting things you highlighted before because nothing stuck.

The vault forces a different loop. After reading a section or watching a lecture, I write a Concept Note in Learning/{subject}/. Not a summary – my understanding. If I cannot explain it in my own words, I do not understand it yet, and that is useful to know.

Then I ask: does this connect to anything in Notes/? Can I extract a permanent note – a cross-domain insight?

Working through linear algebra:

• Concept Note in Learning/Math/Linear-Algebra/: eigenvalues
• Then in Notes/: Eigenvalues are to matrix transformations what CAD constraints are to parametric models -- they identify the invariant structure

That second note is mine. Nobody wrote it in a textbook. It is hooked into my mental model of CAD, which I think about constantly. I will not forget it.

This is the compounding effect the system is supposed to produce. Your STEM learning starts talking to your project work. The graph of connected notes becomes a map of your actual understanding, not a collection of things you have read.

Wiring an AI agent into the vault

The last piece is automation. I use Hermes (my local AI agent) to read and write to the vault directly.

Before any research task, Hermes searches Notes/ and Learning/ for what I already know. This prevents re-deriving things and surfaces relevant context automatically. If I ask it to explain something I have already written a concept note on, it reads the note first and builds on my existing understanding rather than explaining from scratch.

After a learning session, Hermes writes structured Concept Notes to the right Learning/ subfolder and extracts candidate permanent notes to Notes/. I review and edit them – the thinking is mine, but the structuring is automated.

For projects, Hermes appends decisions to the decisions log table in the relevant Project Note. Every non-obvious decision gets a row: what was decided, why. This sounds like overhead. It pays back immediately the first time you pick up a paused project and actually remember why you made the choices you did.

What I skip

I do not write notes for things I can re-derive in five minutes. I do not write notes for things that are already in the code, the commit history, or the PR description. I do not write notes to feel productive.

The weekly review is Sunday, twenty minutes. Process Inbox, promote or delete every note, update status tags on Learning notes (seedling – just captured, growing – building understanding, evergreen – solid and stable), write or update one permanent note. If the review takes longer than twenty minutes, the system is too complicated.

Delete freely. A cluttered vault is a dead vault. If a note has not been touched in six months and is not evergreen, archive it or delete it.

The real test

The system works if, six months from now, I can open the vault and quickly surface what I actually think about a topic – not what I have read about it, but what I understand and how it connects to everything else I am working on.

The graph view in Obsidian will show clusters. Notes in the CS cluster linking to notes in the Projects cluster. An insight from linear algebra linking to a CNCFlow architecture decision. A note on organic growth on X linking to a note on network effects from graph theory.

Those links are the point. Not the notes themselves – the connections between them. That is the second brain: not a better filing cabinet, but a map of how your own thinking connects.

Except there was a gap. Every streaming call cost $0.00 in the ledger. Silently. No error, no warning – just wrong numbers.

I found the gap, fixed it, and got the PR merged. This is the story of how streaming cost tracking actually works.

What AgentBudget does

AgentBudget is an open-source SDK that puts a hard dollar limit on AI agent sessions. Two lines, no infrastructure:

1import agentbudget
2agentbudget.init("$5.00")

It works by monkey-patching Completions.create (OpenAI) and Messages.create (Anthropic) at init time. Every call goes through a wrapper that looks up the model cost, accumulates spend, and raises BudgetExhausted when the limit is hit.

The non-streaming path worked fine. The streaming path did not.

The bug

When stream=True, the patched method receives a Stream object back from the SDK – not a completed response with token counts. The original code had no handling for this case. It silently passed the stream through untracked.

Every streaming call registered as $0.00 in the ledger. Any agent using streaming could blow past its budget with zero resistance. The circuit breaker was blind to half its traffic.

Why streaming is harder to cost

Non-streaming is straightforward: the response comes back with a usage object containing prompt_tokens and completion_tokens. Multiply by the per-token rate, done.

Streaming returns a sequence of chunks. Token counts are not available upfront – they only appear after the stream is exhausted. For OpenAI specifically, usage data on the final chunk is opt-in: you need stream_options={"include_usage": True} in the request, otherwise the final chunk carries no usage data and there is nothing to cost.

Anthropic handles it differently. Usage data is always present, split across two events: message_start carries input tokens, message_delta carries output tokens at the end.

The fix: transparent wrapper classes

The solution is four wrapper classes that intercept the stream, yield every chunk unchanged, and record cost after the iterator is exhausted:

Each wrapper is fully transparent to the caller. The existing code pattern – for chunk in stream: or async for chunk in stream: or with client.stream(...) as stream: – continues to work without any changes.

The wrapper accumulates token counts as chunks arrive, then records the cost in the session ledger once the stream ends.

For OpenAI:

 1class _OpenAIStreamWrapper:
 2    def __init__(self, stream, session, model):
 3        self._stream = stream
 4        self._session = session
 5        self._model = model
 6
 7    def __iter__(self):
 8        for chunk in self._stream:
 9            # Track usage from the final chunk
10            if chunk.usage:
11                cost = price(self._model, chunk.usage)
12                self._session.record(cost)
13            yield chunk
14
15    # Full protocol: __enter__, __exit__, close()

For Anthropic, the accumulation spans two event types:

 1class _AnthropicStreamWrapper:
 2    def __iter__(self):
 3        input_tokens = 0
 4        output_tokens = 0
 5        for event in self._stream:
 6            if event.type == "message_start":
 7                input_tokens = event.message.usage.input_tokens
 8            elif event.type == "message_delta":
 9                output_tokens = event.usage.output_tokens
10            yield event
11        cost = price(self._model, input_tokens, output_tokens)
12        self._session.record(cost)

The detection of whether a response is a stream happens via isinstance checks guarded by ImportError, so the wrapper degrades gracefully if only one SDK is installed.

Implementing the full protocol

The tricky part is not the cost tracking logic – it is making the wrapper implement the full stream protocol correctly.

Python streams support multiple usage patterns: iterator (for chunk in stream), context manager (with stream), async iterator, async context manager, and explicit close()/aclose(). Missing any of these means certain callers will break with an AttributeError or a resource leak.

The wrapper needs to implement all of them:

 1# Sync: iterator + context manager + close
 2def __iter__(self): ...
 3def __enter__(self): return self
 4def __exit__(self, *args): self.close()
 5def close(self): self._stream.close()
 6
 7# Async: async iterator + async context manager + aclose
 8async def __aiter__(self): ...
 9async def __aenter__(self): return self
10async def __aexit__(self, *args): await self.aclose()
11async def aclose(self): await self._stream.aclose()

Getting this wrong is invisible in unit tests with mocks but breaks immediately against real SDK objects.

Tests

The PR added 19 tests covering:

• Cost recorded correctly after stream exhaustion
• Chunks with no usage data skipped without error
• Passthrough identity – every chunk the caller sees is unchanged
• BudgetExhausted propagates correctly mid-stream
• Both for chunk in stream: and with client.stream() as stream: patterns
• close() and aclose() delegation to the underlying stream
• Drop-in mode (agentbudget.init()) wrapping end-to-end
• No-session noop – if no budget session is active, streaming is fully transparent

All 129 pre-existing tests continued to pass. 148 total passing at merge.

The known limitation

OpenAI streaming requires the caller to pass stream_options={"include_usage": True}. Without it, the final chunk carries no usage data, and the cost is silently $0.

This is OpenAI’s API behaviour – usage data on streams is opt-in. The limitation is documented in the module docstring. A future improvement could auto-inject the option at the patch layer, but that requires modifying the outbound request, which is a bigger change than this PR intended to be.

Anthropic has no equivalent limitation – usage is always present.

What I learned

Transparent wrappers need the full protocol. It is tempting to implement just __iter__ and call it done. But real callers use context managers, explicit close, and async variants. Implementing the minimum breaks production code in ways that are hard to debug.

Streaming costs are provider-specific. OpenAI and Anthropic have different conventions for where usage data appears in the stream. Any SDK that claims to support both needs to handle both separately.

Test against real SDK objects, not just mocks. The isinstance detection and chunk structure only behave correctly against live SDK classes. Mock-based tests passed for the wrong reasons until I verified against an actual installed SDK.

Links

• PR #6 – feat: track costs for streaming OpenAI and Anthropic responses
• AgentBudget on GitHub
• PyPI

This is the story of setting that up in one session, and the parts that went sideways.

The Stack

Four moving parts:

• Bifrost – LLM gateway already running on localhost:24242, routing to Ollama cloud models
• Hermes Agent – open-source AI agent framework by Nous Research, pointed at Bifrost
• Ollama – cloud relay for gemma4 and qwen3.5 cloud models via ollama.com
• Camoufox – Firefox fork with TLS fingerprint spoofing for scraping tasks

The goal was to have Hermes run as a Telegram bot so I could assign it tasks from my phone, with all model traffic flowing through Bifrost so routing stays centralized.

Bifrost First

Bifrost was already up on port 24242 with Ollama configured. The only addition needed was an ollama-cloud provider pointing at https://ollama.com rather than localhost. This is a non-obvious distinction.

The trap: Ollama’s OpenAI-compatible endpoint (/v1/chat/completions) does not work for cloud models. It hangs. Cloud models only work through Ollama’s native /api/chat endpoint. Pointing Bifrost directly at https://ollama.com instead of localhost:11434 bypasses the broken compat layer and hits the right path.

Once the provider was registered and OLLAMA_API_KEY was set in .zshrc, both cloud models confirmed working:

1ollama pull gemma4:31b-cloud
2ollama pull qwen3.5:cloud

Installing Hermes

1curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

That puts everything under ~/.hermes/. The setup wizard runs next:

1hermes setup

It walks through provider selection interactively. I pointed it at the Bifrost custom endpoint (http://localhost:24242/v1) and picked ollama-cloud/gemma4:31b-cloud as the default model.

Key config paths:

~/.hermes/config.yaml    -- main settings
~/.hermes/.env           -- secrets and API keys
~/.hermes/skills/        -- reusable agent procedures
~/.hermes/sessions/      -- full conversation history (searchable)

After setup, a quick smoke test confirmed the agent was up and routing through Bifrost correctly:

1hermes chat -q "what model are you using and where does traffic go"

Context Window

The default context length was under 20k tokens. Ollama cloud models support much larger windows. One config set:

1hermes config set model.context_length 200000

Takes effect on the next session restart.

Telegram Bot

This is where Hermes gets genuinely useful. The gateway turns it into a bot that accepts tasks from any platform you connect.

Create a bot via BotFather, get the token, then add it to ~/.hermes/.env:

1TELEGRAM_BOT_TOKEN=<your-bot-token>
2TELEGRAM_ALLOWED_USERS=<your-numeric-telegram-id>

TELEGRAM_ALLOWED_USERS takes the numeric user ID, not the username. Lock it down. Anyone who finds the bot URL can send it commands if this is not set.

Start the gateway:

1hermes gateway run

For persistent background operation, install it as a service:

1hermes gateway install
2hermes gateway start

A set of aliases in .zshrc makes it easier to manage day to day:

1alias hermes-gateway-start="hermes gateway start"
2alias hermes-gateway-stop="hermes gateway stop"
3alias hermes-gateway-log="tail -f ~/.hermes/logs/gateway.log"

First run hit a missing Python dependency and failed silently. The fix was running hermes gateway run in the foreground once to see the real error, installing the missing package, then moving back to the service.

Camoufox

Camoufox is a Firefox fork built for scraping. It spoofs TLS fingerprints so sites see a legitimate browser rather than a Playwright or CDP signature. It exposes a CDP endpoint that Hermes’s browser tool connects to.

1git clone https://github.com/daijro/camoufox
2cd camoufox && npm install
3python -m camoufox fetch   # ~300MB download

The camoufox fetch step downloads the actual browser binary and does not run automatically via postinstall. If you skip it, the first start fails silently. Run it manually and wait for the download to finish before starting the server.

Start it on port 9377:

1python -m camoufox server --port 9377 &

Smoke test via Hermes:

1hermes chat -q "use the browser to fetch the title of example.com"

Aliases for day-to-day:

1alias camofox-start="python -m camoufox server --port 9377 &"
2alias camofox-stop="pkill -f 'camoufox server'"

What Actually Went Wrong

Ollama native vs compat endpoint. Already covered above, but it cost a couple of hours. If a cloud model hangs at the provider level, check whether your gateway is talking to the right API path.

Camoufox silent failure. The binary fetch is not in postinstall. No error, just no browser. Always run python -m camoufox fetch explicitly before the first start.

Hermes gateway dependency. First start printed nothing useful. Run in foreground before daemonizing so you can see the actual error.

Bifrost and empty API keys. Ollama initially rejected non-empty dummy keys in the Authorization header. Setting the key to an empty string before switching to the real OLLAMA_API_KEY got things unstuck. The order mattered.

Session corruption in OpenCode. An OpenCode session used to orchestrate this setup got a zombie assistant message from an interrupted stream. The message had an empty string for content. Bifrost converted that empty string to null before forwarding, and the upstream provider rejected the entire next request with messages.315.member.content must not be null. Every retry included the same zombie in history, so the error was permanent until manually fixed.

The fix is to delete the zombie row directly from the OpenCode SQLite database:

1sqlite3 ~/.local/share/opencode/opencode.db \
2  "DELETE FROM message WHERE id = '<zombie-message-id>' AND session_id = '<session-id>';"

There is no built-in repair command. Back up the database before editing it.

Final State

Services running when done:

bifrost    :24242  -- Ollama cloud routes
ollama     :11434  -- cloud relay (gemma4, qwen3.5)
camoufox   :9377   -- CDP browser endpoint
hermes     gateway -- Telegram bot (restricted to single user)

The agent receives messages on Telegram, runs tool calls locally (terminal, browser, file ops, web search), and routes all model traffic through Bifrost.

What’s Left

The original plan included running a local Qwen3.5-27B model via llama.cpp with Metal acceleration. That is a 13.5GB download and a build-from-source step, so it was deferred to the next session. The cloud routing setup works fine in the meantime.

References

• Hermes Agent: https://github.com/NousResearch/hermes-agent
• Hermes docs: https://hermes-agent.nousresearch.com/docs/
• Bifrost: https://github.com/maximhq/bifrost
• Camoufox: https://github.com/daijro/camoufox
• OpenCode: https://opencode.ai

So I built freeseek-proxy: a local proxy that sits between OpenAI-compatible clients (opencode, Claude Code, any SDK) and DeepSeek’s web chat backend. You send standard /v1/chat/completions requests; it handles sessions, PoW, TLS fingerprinting, and SSE translation behind the scenes.

This post covers the four hardest problems I had to solve.

The architecture (it’s two processes, not one)

The proxy is split into two halves that talk over localhost:

                  ┌──────────────────────────┐
                  │   Client                 │
                  │   (opencode / curl / SDK)│
                  └────────────┬─────────────┘
                               │
                  POST /v1/chat/completions
                       (OpenAI format)
                               │
                  ┌────────────▼─────────────┐
                  │   TypeScript Proxy       │
                  │   Hono on Bun :9123      │
                  │                          │
                  │   · Request normalization│
                  │   · Tool-call compat     │
                  │   · SSE reformatting     │
                  │   · Session management   │
                  └────────────┬─────────────┘
                               │
                    HTTP localhost:8081
                               │
                  ┌────────────▼─────────────┐
                  │   Python Backend         │
                  │   FastAPI + uvicorn      │
                  │                          │
                  │   · curl_cffi (TLS spoof)│
                  │   · WASM PoW solver      │
                  │   · Cookie management    │
                  │   · Auth (token / login) │
                  └────────────┬─────────────┘
                               │
                   HTTPS chat.deepseek.com
                               │
                  ┌────────────▼─────────────┐
                  │      DeepSeek API        │
                  └──────────────────────────┘

Why two languages? DeepSeek does browser fingerprinting. Their servers check TLS fingerprints, and if yours looks like python-requests or node-fetch, you get blocked. The Python side uses curl_cffi with impersonate="chrome120" to produce a TLS handshake indistinguishable from Chrome. The TypeScript side handles everything else — request translation, streaming, tool calls — where Bun’s performance and type safety matter more.

Problem 1: Proof-of-Work with a WASM SHA3 solver

DeepSeek doesn’t just check your auth token. Before every chat completion, you must solve a Proof-of-Work challenge. The flow is:

1. Request a challenge from /api/v0/chat/create_pow_challenge
2. The server returns a challenge string, salt, difficulty, and expiry
3. You run a SHA3-based hash computation until you find a valid answer
4. Encode the answer as base64 JSON and send it as x-ds-pow-response header

The catch: DeepSeek’s PoW algorithm is implemented in a WebAssembly module. In the browser, this runs natively. Outside the browser, you need a WASM runtime.

The solver uses wasmtime (a standalone WASM runtime for Python) to load DeepSeek’s own sha3_wasm_bg.wasm binary and call its exported wasm_solve function:

 1class DeepSeekHash:
 2    def init(self, wasm_path: str):
 3        engine = wasmtime.Engine()
 4        with open(wasm_path, "rb") as f:
 5            wasm_bytes = f.read()
 6        module = wasmtime.Module(engine, wasm_bytes)
 7        self.store = wasmtime.Store(engine)
 8        linker = wasmtime.Linker(engine)
 9        linker.define_wasi()
10        self.instance = linker.instantiate(self.store, module)
11        self.memory = self.instance.exports(self.store)["memory"]
12        return self
13
14    def calculate_hash(self, algorithm, challenge, salt, difficulty, expire_at):
15        prefix = f"{salt}_{expire_at}_"
16        # Allocate WASM memory, write challenge + prefix
17        challenge_ptr, challenge_len = self._write_to_memory(challenge)
18        prefix_ptr, prefix_len = self._write_to_memory(prefix)
19        # Call the exported solver
20        self.instance.exports(self.store)["wasm_solve"](
21            self.store, retptr,
22            challenge_ptr, challenge_len,
23            prefix_ptr, prefix_len,
24            float(difficulty),
25        )
26        # Read the answer from WASM memory
27        value_bytes = bytes(memory_view[retptr + 8 : retptr + 16])
28        value = np.frombuffer(value_bytes, dtype=np.float64)[0]
29        return int(value)

The memory management is manual — you allocate via __wbindgen_export_0, write UTF-8 bytes one at a time, call the solver, then read the result from a return pointer. Stack pointer cleanup happens in a finally block. It’s the kind of code where one off-by-one error means silent corruption.

Why Python 3.11 specifically? The wasmtime + numpy + curl_cffi stack was verified working on 3.11. Python 3.14 caused silent failures in the WASM path during testing — the process would get killed mid-computation with no error message. This isn’t a “should work” situation; it’s a “was tested and doesn’t” situation.

Problem 2: TLS fingerprinting and Cloudflare

DeepSeek sits behind Cloudflare. Standard HTTP clients get 403s or “Just a moment…” challenge pages because their TLS Client Hello doesn’t match what a real browser sends.

The fix is curl_cffi with browser impersonation:

1response = requests.post(
2    f"{BASE_URL}{path}",
3    headers=headers,
4    json=body,
5    cookies=cookies,
6    impersonate="chrome120",  # TLS fingerprint matches Chrome 120
7    stream=stream,
8)

impersonate="chrome120" makes the TLS handshake (cipher suites, extensions, ALPN) identical to Chrome 120. This is why the backend is Python, not Node — there’s no equivalent library in the JS ecosystem that matches real browser TLS fingerprints this precisely.

The cookie management layer adds another defense: if a request hits Cloudflare anyway, the proxy can automatically refresh cookies via a configurable shell command:

1def refresh_cookies(self) -> dict[str, str]:
2    if not self.refresh_command:
3        return self.load_cookies()
4    subprocess.run(self.refresh_command, shell=True, check=True)
5    cookies = self.load_cookies()
6    self.save_cookies(cookies)
7    return cookies

This lets you plug in whatever cookie extraction tool you prefer — a headless browser script, a browser extension export, etc.

Problem 3: Translating SSE formats

DeepSeek’s streaming format is not OpenAI’s streaming format. Both use Server-Sent Events, but the payload structure is completely different.

OpenAI format (what clients expect):

1data: {"choices":[{"delta":{"content":"Hello"},"index":0}],"model":"gpt-4"}

DeepSeek format (what the server sends):

1data: {"v":{"response":{"fragments":[{"type":"text","content":"Hello"}]}},"o":"APPEND"}

DeepSeek uses a nested structure where content lives inside response.fragments, operations can be APPEND, SET, or BATCH, and thinking content is separated from regular content by fragment type. There’s also metadata like response/status and response/accumulated_token_usage mixed into the stream that clients don’t want.

The proxy handles this translation in parseSSELine and extractDeepSeekContent:

 1function extractDeepSeekContent(
 2  data: DeepSeekSSEData,
 3  includeThinking: boolean
 4): string {
 5  // DeepSeek nests content in multiple possible locations
 6  const target = data.v?.response ?? data.response ?? data;
 7  const fragments = target?.fragments;
 8
 9  if (Array.isArray(fragments)) {
10    return fragments
11      .filter(f => includeThinking || f.type !== "thinking")
12      .map(f => f.content)
13      .join("");
14  }
15
16  // Fallback: direct content field
17  if (typeof data.v === "string") return data.v;
18  if (typeof data.content === "string") return data.content;
19  return "";
20}

For streaming responses, each DeepSeek SSE chunk gets translated into an OpenAI chat.completion.chunk on the fly. For non-streaming, the proxy accumulates all chunks, then builds a single chat.completion response.

Problem 4: Tool calls on a model that doesn’t support them

This is the most interesting problem. DeepSeek’s web chat API doesn’t support OpenAI-style tool calls. There’s no tools parameter, no tool_choice, no tool_calls in the response. But clients like opencode and Claude Code rely heavily on tool use — without it, the agent can’t read files, run commands, or interact with your codebase.

The solution is a prompt-engineering compatibility layer. When the proxy detects tool-related fields in the request, it:

1. Injects a system prompt describing available tools and the expected JSON format
2. Flattens the conversation into a single prompt (including tool results from previous turns)
3. Parses the model’s response for JSON tool call envelopes
4. Translates back into OpenAI’s tool_calls format

The injected system prompt instructs the model to output tool calls as JSON:

 1function buildToolSystemPrompt(tools, toolChoice) {
 2  return [
 3    "You are replying through an OpenAI-compatible proxy that supports tool use.",
 4    toolChoiceRule, // varies by mode: auto/required/none/function
 5    `If you decide to call a tool, output only valid JSON with this exact shape:`,
 6    `{"opencode_tool_call": {"name": "tool_name", "arguments": { ... }}}.`,
 7    `For multiple calls: {"opencode_tool_calls": [...]}.`,
 8    "Do not wrap the JSON in markdown.",
 9    "Available tools:",
10    availableTools, // name, description, JSON schema for each
11  ].join("\n\n");
12}

The conversation history gets flattened because DeepSeek’s chat API takes a single prompt string, not an array of messages:

 1function formatConversationForDeepSeek(messages) {
 2  return messages.map(message => {
 3    if (message.role === "system") return `System: ${content}`;
 4    if (message.role === "user") return `User: ${content}`;
 5    if (message.role === "assistant") {
 6      if (message.tool_calls?.length)
 7        return `Assistant tool request: ${formatted calls}`;
 8      return `Assistant: ${content}`;
 9    }
10    if (message.role === "tool")
11      return `Tool (${message.tool_call_id}) result: ${content}`;
12  }).join("\n\n");
13}

On the response side, parseToolEnvelope scans the model output for JSON objects containing opencode_tool_call or opencode_tool_calls keys, validates that the function names match known tools, and converts them into proper OpenAI tool_calls with generated IDs:

 1function parseToolEnvelope(text, tools) {
 2  for (const candidate of extractJsonObjectCandidates(text.trim())) {
 3    const payload = JSON.parse(candidate);
 4    const rawCalls = payload.opencode_tool_calls ?? [payload.opencode_tool_call];
 5    const toolCalls = rawCalls
 6      .filter(call => tools.some(t => t.function.name === call.name))
 7      .map(call => ({
 8        id: `call_${uuidv4()}`,
 9        type: "function",
10        function: { name: call.name, arguments: JSON.stringify(call.arguments) },
11      }));
12    if (toolCalls.length) return { toolCalls };
13  }
14  return null;
15}

The JSON extraction is deliberately robust — it uses a bracket-depth parser to find JSON objects embedded in natural language, handles escaped strings, and tries multiple candidates. This matters because the model sometimes wraps tool calls in explanatory text despite being told not to.

For streaming with tools, there’s an extra step. The proxy can’t stream tool calls token-by-token (the client needs the complete tool call object). So when tools are present, the proxy collects the full response first, parses tool calls, then re-streams the result as a synthetic SSE sequence. This adds ~latency but is the only correct approach.

What the client sees

After all this translation, what comes out the other end is a standard OpenAI response:

1curl http://localhost:9123/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "deepseek-chat",
5    "messages": [{"role": "user", "content": "Hello"}],
6    "stream": true
7  }'

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"index":0}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"!"},"index":0}]}
data: [DONE]

Indistinguishable from OpenAI. Any client that speaks the OpenAI protocol works without modification.

What I learned

WASM outside the browser is viable but fragile

The wasmtime runtime works, but debugging WASM memory issues from Python is miserable. There’s no stack trace when you read the wrong offset — you just get garbage bytes. The debug flags in pow.py exist because I needed them.

TLS fingerprinting is the real gate, not auth tokens

I initially thought the hard part would be authentication. It wasn’t. The hard part was making HTTP requests that don’t get blocked. curl_cffi with browser impersonation is the only reliable solution I found for Python. If you’re building any kind of web scraper or API proxy in 2026, TLS fingerprinting is the first problem you’ll hit.

Tool call compatibility via prompting is surprisingly reliable

I expected the prompt-engineering approach to tool calls to be flaky. It’s not. DeepSeek’s models are good at following structured output instructions, and the JSON extraction parser handles edge cases well. The key is being very explicit about the expected format and validating against the known tool list.

Two-process architecture was the right call

Splitting into TypeScript + Python felt like overengineering at first. It wasn’t. Each language does what it’s best at: Python for the “pretend to be a browser” parts (TLS, WASM), TypeScript for the “translate between API formats” parts (streaming, types, request handling). Trying to do both in one language would have meant worse tooling for at least half the problem.

Links

• Repo: freeseek-proxy
• curl_cffi: docs — Python HTTP client with browser TLS impersonation
• wasmtime-py: GitHub — Python bindings for the Wasmtime WASM runtime
• Hono: hono.dev — Lightweight web framework for Bun/Node/Deno

Except it doesn’t. It concatenates them all into one call: search_documentsget_usersearch_documents. The agent hallucinates, retries, and loops. I stared at the telemetry for twenty minutes before I realized the bug wasn’t in the agent — it was in the gateway’s streaming accumulator.

This is the story of how I found and fixed a parallel tool call merging bug in Bifrost, a 2.6k-star open-source AI gateway.

What is Bifrost?

Bifrost is a high-performance AI gateway written in Go. It sits between your application and LLM providers (OpenAI, Anthropic, Bedrock, Vertex, etc.), providing a unified OpenAI-compatible API with automatic failover, load balancing, semantic caching, and streaming support. Think of it as an intelligent reverse proxy for AI — one API, fifteen providers, ~11µs overhead at 5k RPS.

The relevant piece here is the streaming accumulator. When you make a streaming chat completion request, the LLM sends back a sequence of Server-Sent Events (SSE), each containing a small delta — a few tokens of text, or a fragment of a tool call’s arguments. The accumulator’s job is to reassemble these deltas into complete messages.

The bug: recency-based routing

Here’s the scenario. You ask Claude or GPT to call two tools in parallel:

User: "Search for compliance circulars about RBI and also get the user's profile"

The model decides to call both search_circulars and get_user_profile simultaneously. During streaming, the provider sends interleaved deltas:

Delta 1: tool_call[0] name="search" (index=0, id=call_abc)
Delta 2: tool_call[1] name="get_us" (index=1, id=call_xyz)
Delta 3: tool_call[0] args='{"query": "RBI'   (index=0)
Delta 4: tool_call[1] args='{"user_id": "u'   (index=1)
Delta 5: tool_call[0] args=' circulars"}'      (index=0)
Delta 6: tool_call[1] args='123"}'             (index=1)

Each delta carries an index (and optionally an id) that identifies which tool call it belongs to. The expected behavior: two distinct tool calls with their own names and arguments.

The actual behavior in Bifrost’s accumulator before the fix:

1// Old logic (simplified)
2if deltaToolCall.Function.Name != nil {
3    // New tool call — create it
4    existingToolCalls = append(existingToolCalls, newToolCall)
5} else {
6    // Argument delta — append to the LAST tool call
7    toolCallToModify = &existingToolCalls[len(existingToolCalls)-1]
8    toolCallToModify.Function.Arguments += deltaToolCall.Function.Arguments
9}

The routing logic was based on recency: if a delta has a Name, it’s a new tool call; otherwise, append arguments to the most recent one. This works perfectly when tool calls arrive sequentially. It breaks completely when they’re interleaved.

With the deltas above:

• Delta 3 (index=0 args) arrives → appended to the last tool call, which is get_user_profile (index=1). Wrong target.
• Delta 5 (index=0 args) arrives → again appended to get_user_profile. Now get_user_profile has arguments from two different calls mashed together.

The result: concatenated tool names, merged arguments, and an agent stuck in a retry loop trying to invoke search_circularsget_user_profile — a tool that doesn’t exist.

Finding the bug

I hit this in production. Our compliance platform uses an AI agent that calls multiple tools in parallel — searching circulars, fetching regulatory data, looking up user context. The agent kept failing with tool resolution errors, and the telemetry showed impossible tool names:

search_circularsearch_circularsearch_circular

At first I suspected the agent’s tool-calling logic. Then I looked at the raw SSE stream from the provider — the deltas were correct. Each one had the right index and id. The corruption was happening between the provider response and the final accumulated message.

I traced it to accumulateToolCallsInMessage in framework/streaming/accumulator.go. The function had no concept of tool call identity. It used the presence of a Name field as a heuristic for “new vs. continuation,” which is fragile and incorrect when deltas arrive out of order.

The fix

The fix is conceptually simple: route deltas by identity, not by recency.

Each tool call delta carries two potential identifiers:

1. tool_call.id — a string like call_abc123 (set by OpenAI/Anthropic)
2. tool_call.index — an integer position (0, 1, 2, …)

The new logic builds lookup maps on existing tool calls and uses them to route each incoming delta to the correct target:

1// Build lookup maps for identity-based routing
2idToIndex := make(map[string]int, len(existingToolCalls))
3indexToIndex := make(map[uint16]int, len(existingToolCalls))
4for i, toolCall := range existingToolCalls {
5    if toolCall.ID != nil && *toolCall.ID != "" {
6        idToIndex[*toolCall.ID] = i
7    }
8    indexToIndex[toolCall.Index] = i
9}

For each incoming delta, routing follows a priority chain:

 1for _, deltaToolCall := range deltaToolCalls {
 2    index := -1
 3
 4    // Priority 1: match by tool_call.id
 5    if deltaToolCall.ID != nil && *deltaToolCall.ID != "" {
 6        if existingIndex, ok := idToIndex[*deltaToolCall.ID]; ok {
 7            index = existingIndex
 8        }
 9    }
10
11    // Priority 2: match by tool_call.index
12    if index == -1 {
13        if existingIndex, ok := indexToIndex[deltaToolCall.Index]; ok {
14            index = existingIndex
15        }
16    }
17
18    // Priority 3: no match → create new tool call (if name present)
19    if index == -1 {
20        if deltaToolCall.Function.Name == nil {
21            // Can't create a tool call without a name
22            continue
23        }
24        newToolCall := schemas.ChatAssistantMessageToolCall{
25            Index:    deltaToolCall.Index,
26            ID:       deltaToolCall.ID,
27            Function: /* ... */,
28        }
29        existingToolCalls = append(existingToolCalls, newToolCall)
30        // Update maps for future deltas
31        indexToIndex[newToolCall.Index] = len(existingToolCalls) - 1
32        if newToolCall.ID != nil {
33            idToIndex[*newToolCall.ID] = len(existingToolCalls) - 1
34        }
35        continue
36    }
37
38    // Append arguments to the correct tool call
39    existingToolCalls[index].Function.Arguments += deltaToolCall.Function.Arguments
40}

The key insight is that the maps are updated as new tool calls are created, so subsequent deltas for the same call always find their target — even if they arrive many chunks later.

The same bug, twice

During code review, a reviewer (Pratham-Mishra04) pointed out that the same recency-based routing existed in a second code path: the Responses API streaming handler in responses.go.

The Responses API is OpenAI’s newer streaming format (the /v1/responses endpoint). It uses ItemID instead of tool_call.index, but the accumulation logic had the same flaw — FunctionCallArgumentsDelta events were always appended to the last message:

1// Old responses.go logic
2if resp.Delta != nil && len(messages) > 0 {
3    // Always targets the last message — wrong for parallel calls
4    a.appendFunctionArgumentsDeltaToResponsesMessage(
5        &messages[len(messages)-1], *resp.Delta)
6}

The fix follows the same pattern: search for a message matching resp.ItemID, and only fall back to the last message when no ItemID is present. If an ItemID exists but no message matches, create a stub message to hold the delta rather than merging it into the wrong call:

 1if resp.Delta != nil && len(messages) > 0 {
 2    targetIdx := len(messages) - 1
 3    if resp.ItemID != nil {
 4        targetIdx = -1
 5        for i := len(messages) - 1; i >= 0; i-- {
 6            if messages[i].ID != nil && *messages[i].ID == *resp.ItemID {
 7                targetIdx = i
 8                break
 9            }
10        }
11        if targetIdx == -1 {
12            // Create stub to avoid merging into wrong message
13            id := *resp.ItemID
14            messages = append(messages, schemas.ResponsesMessage{ID: &id})
15            targetIdx = len(messages) - 1
16        }
17    }
18    a.appendFunctionArgumentsDeltaToResponsesMessage(
19        &messages[targetIdx], *resp.Delta)
20}

Testing parallel accumulation

The regression test simulates the exact interleaving pattern that triggers the bug:

 1func TestAccumulateToolCallsInterleavedParallel(t *testing.T) {
 2    // ...
 3    toolCallID0 := "call_0"
 4    toolCallID1 := "call_1"
 5    toolNameAdd := "add"
 6    toolNameMultiply := "multiply"
 7
 8    // Simulate interleaved deltas
 9    accumulate(makeDelta(0, &toolCallID0, &toolNameAdd, ""))       // create call 0
10    accumulate(makeDelta(1, &toolCallID1, &toolNameMultiply, ""))  // create call 1
11    accumulate(makeDelta(0, nil, nil, `{"a": 1`))                  // args for call 0
12    accumulate(makeDelta(1, nil, nil, `{"a": 2`))                  // args for call 1
13    accumulate(makeDelta(0, nil, nil, `, "b": 3}`))                // more args for call 0
14    accumulate(makeDelta(1, nil, nil, `, "b": 4}`))                // more args for call 1
15
16    // Assert: two distinct tool calls with correct arguments
17    assert(addCall.Arguments == `{"a": 1, "b": 3}`)
18    assert(multiplyCall.Arguments == `{"a": 2, "b": 4}`)
19}

Without the fix, add would end up with multiply’s arguments concatenated in. With the fix, each call accumulates only its own deltas.

A second test covers the Responses API path with ItemID-based routing, using the same interleaving pattern but with OutputItemAdded + FunctionCallArgumentsDelta events.

The PR lifecycle

I filed Issue #1829 with reproduction details from production telemetry, then opened PR #1830 with the fix and tests.

The review process was smooth:

1. First commit: fix the Chat Completions accumulator + regression test
2. Reviewer feedback: same bug exists in Responses API — please fix there too + add changelog entries
3. Second commit: fix Responses API routing + regression test + changelogs
4. Merged by akshaydeo (Bifrost maintainer)

Total: 3 commits, ~280 lines of Go across 5 files. Same-day turnaround from issue to merge.

What I learned

1. Recency is not identity

The original code used position (last element) as a proxy for identity. This is a common pattern in sequential streaming — and it works, until the stream isn’t sequential. The fix is to use the actual identity field that the protocol already provides.

This is a general principle: if the protocol gives you an ID field, use it. Don’t rely on ordering assumptions that hold today but break when concurrency enters.

2. The same bug pattern repeats across API surfaces

Bifrost supports two streaming formats: Chat Completions (the classic tool_calls array) and Responses API (the newer ItemID-based format). Both had the same routing flaw because the accumulation logic was duplicated rather than shared. The reviewer catching this in a different file was the most valuable part of the review.

3. OSS contributions are about context, not complexity

The fix itself is straightforward — build a map, use it for lookup. The hard part was:

• Finding the bug in a codebase I’d never seen before
• Understanding why the existing approach was wrong
• Testing with realistic interleaved deltas
• Responding to review feedback about a parallel code path I hadn’t initially noticed

The code change was ~100 lines. The context-building was hours.

4. Production telemetry is the best bug report

The issue report included the exact malformed tool name from production: search_circularsearch_circularsearch_circular. That single string made the bug immediately reproducible and the fix trivially verifiable. If you’re filing a bug, include the malformed output — it’s worth more than a paragraph of description.

Links

• PR: fix: preserve parallel tool call deltas — #1830
• Issue: Streaming tool call deltas merge in parallel tool calling — #1829
• Project: Bifrost AI Gateway — 2.6k ⭐, fastest enterprise AI gateway

The tasks were small. The backlog was not. This is the worst possible combo for a normal workflow because the fixed overhead dominates: branch setup, dependency sync, commits, reviewable diffs, and PR management. Doing it serially feels safe, but it is slow in a way that doesn’t show up in estimates.

So I tried the obvious cheat: run multiple AI agents in parallel.

It worked, but only after I tripped over three problems that are easy to reproduce if you try this without thinking through git state, shells, and sandbox boundaries.

What the system looked like (so you don’t think this is a demo problem)

I ended up writing a small orchestration script with three phases:

1. Create (or reuse) one worktree per task.
2. Install dependencies in parallel.
3. Run codex exec in batched parallel, then push branches and open draft PRs.

The key detail is that batching wasn’t “run everything at once”. It was “parallel within a batch, sequential across batches”, grouped by expected file overlap.

Here is the redacted shape of the script (this is not pseudocode; it’s a sanitized skeleton of what I ran):

 1#!/usr/bin/env zsh
 2set -euo pipefail
 3
 4WORKTREE_DIR=".worktrees"
 5BASE_BRANCH="<base-branch>"
 6LOG_DIR="${WORKTREE_DIR}/_logs"
 7
 8mkdir -p "${WORKTREE_DIR}" "${LOG_DIR}"
 9
10# Phase 1: worktrees + deps (parallel installs)
11hdr "Phase 1: Setting up worktrees"
12git worktree add -b "<feature-branch>" "${WORKTREE_DIR}/<lane>" "${BASE_BRANCH}"
13(cd "${WORKTREE_DIR}/<lane>/frontend" && bun install --frozen-lockfile) &
14(cd "${WORKTREE_DIR}/<lane>/backend"  && uv sync) &
15wait
16
17# Phase 2: batched parallel codex exec (one log per lane)
18hdr "Phase 2: Running Codex"
19codex exec --dangerously-bypass-approvals-and-sandbox -C "${WORKTREE_DIR}/<lane>" -m "${CODEX_MODEL}" "<prompt>" > "${LOG_DIR}/<lane>.log" 2>&1 &
20wait
21
22# Phase 3: push + PRs
23hdr "Phase 3: PRs to ${BASE_BRANCH}"
24git -C "${WORKTREE_DIR}/<lane>" push -u origin "<feature-branch>"
25gh pr create --base "${BASE_BRANCH}" --head "<feature-branch>" --draft --body "<templated body>"

Notice what this gives you immediately: one directory per lane, one log file per lane, and a clean boundary between “make changes” and “publish changes”.

Now for the parts that went wrong.

Failure #1: The shell lied about what “Bash” means

The first failure happened before any parallelism even started. The orchestration was written with associative arrays, and the system shell rejected it with:

1declare: -A: invalid option

This is the kind of bug that looks embarrassing until you realize it is inevitable. macOS ships an older Bash; other environments may default to sh; CI runners may use different interpreters. If your control-plane script can’t build the lane-to-branch mapping reliably, your entire run becomes a dice roll.

The fix was not “make it work on my machine”. The fix was pinning the interpreter and failing fast (set -euo pipefail). Once the script ran under the interpreter it was written for, this class of failure disappeared.

Failure #2: The sandbox was fine until it touched .git

The second failure was more instructive: everything looked successful until commit/push time, and then git failed when trying to write worktree metadata:

1fatal: Unable to create '.git/worktrees/<lane>/index.lock': Operation not permitted

The important mental model is: “can edit files” is not equivalent to “can finish delivery”. Git history mutation needs to create locks and update metadata under .git/. Sandboxed agents often allow workspace file edits while denying .git writes by design.

The fix is to treat permissions as architecture. In my runbook now, implementation and version-control mutation are distinct phases. I keep guardrails on while generating and editing code, and only elevate privileges for commit, rebase, push, and PR creation. That sounds procedural, but it is the difference between parallelism and chaos.

Failure #3: The PR diff was computed against the wrong reality

The third failure was the “ghost diff” class: the PR contained changes that “weren’t part of the task” even though the worktree looked clean locally. This is not a GitHub bug. It is a merge-base bug.

PR diff is computed from:

1merge_base(feature, base) .. feature

If your base ref is stale when the feature branch is compared, merge_base resolves behind your intended base, and commits that should be “already in base” appear as if they were introduced by the feature.

The only reliable approach is to verify ancestry before review and rebase if needed:

1git merge-base --is-ancestor origin/<base-branch> HEAD || echo REBASE_REQUIRED
2git diff --name-only origin/<base-branch>...HEAD

This takes seconds and saves you from burning reviewer attention on diff noise.

What changed once I actually read the Codex CLI docs

My first attempt treated Codex like a generic shell command that prints code. The docs made the control surface explicit, and that changed how I designed the run.

Approval and sandbox mode became part of the plan instead of an afterthought. Configuration precedence became something I could reason about when a lane behaved differently. Non-interactive codex exec became the default because it is scriptable and produces logs you can archive. And built-in review flows (like /review) became a lane-local quality gate before humans ever see the PR.

I also stopped mixing two different kinds of parallelism. Worktrees are for isolating tasks across lanes. Multi-agent mode is for decomposing one task inside a lane. When you treat them as separate tools, your system stays debuggable.

The boring checklist

At this point the process is intentionally boring, which is exactly what you want near a deadline. My checklist is short:

• If the lane can’t commit/push, it doesn’t “count” as done. Fix the permission boundary first.
• If the PR diff scope isn’t what you expect, stop and fix ancestry before asking for review.
• If a lane doesn’t have a log file, assume it didn’t run deterministically.

Appendix: Redacted Script Skeleton

Below is a condensed, anonymized skeleton of the script I used. It preserves the mechanics (worktrees, batching, logs, PR creation) but removes identity details.

 1#!/usr/bin/env zsh
 2set -euo pipefail
 3
 4BASE_BRANCH="<base-branch>"
 5WORKTREE_DIR=".worktrees"
 6LOG_DIR="${WORKTREE_DIR}/_logs"
 7
 8mkdir -p "${WORKTREE_DIR}" "${LOG_DIR}"
 9
10typeset -A TASK_BRANCH TASK_TITLE TASK_PLAN TASK_LABEL
11TASK_BRANCH[001]="feature/lane-001"
12TASK_TITLE[001]="Lane 001: <title>"
13TASK_PLAN[001]="docs/plans/<plan>.md"
14TASK_LABEL[001]="<label>"
15
16BATCH_1=(001 002)
17BATCH_2=(003)
18
19setup_lane() {
20  local id="$1"
21  local branch="${TASK_BRANCH[$id]}"
22  local worktree="${WORKTREE_DIR}/lane-${id}"
23
24  if [[ -d "${worktree}" ]]; then
25    echo "Reusing ${worktree}"
26  else
27    git worktree add -b "${branch}" "${worktree}" "${BASE_BRANCH}"
28  fi
29
30  (cd "${worktree}/frontend" && bun install --frozen-lockfile) &
31  (cd "${worktree}/backend"  && uv sync) &
32  wait
33}
34
35run_lane() {
36  local id="$1"
37  local worktree="${WORKTREE_DIR}/lane-${id}"
38  local log="${LOG_DIR}/lane-${id}.log"
39  local prompt="<redacted prompt built from plan + conventions>"
40
41  codex exec --dangerously-bypass-approvals-and-sandbox -C "${worktree}" "${prompt}" > "${log}" 2>&1
42}
43
44create_pr() {
45  local id="$1"
46  local branch="${TASK_BRANCH[$id]}"
47  local title="${TASK_TITLE[$id]}"
48  local worktree="${WORKTREE_DIR}/lane-${id}"
49
50  git -C "${worktree}" push -u origin "${branch}"
51  gh pr create --base "${BASE_BRANCH}" --head "${branch}" --draft --title "${title}" --body "<templated body>"
52}

References

• Codex docs hub: https://developers.openai.com/codex
• Codex CLI overview: https://developers.openai.com/codex/cli
• Codex CLI features: https://developers.openai.com/codex/cli/features
• Codex multi-agent docs: https://developers.openai.com/codex/multi-agent
• Codex security/sandbox docs: https://developers.openai.com/codex/security
• Codex config basics: https://developers.openai.com/codex/config-basic
• Codex config reference: https://developers.openai.com/codex/config-reference
• Codex CLI GitHub README: https://github.com/openai/codex/blob/main/README.md
• Ralph loop agent (Vercel Labs): https://github.com/vercel-labs/ralph-loop-agent
• Ralph from first principles (Geoffrey Huntley): https://www.youtube.com/watch?v=4Nna09dG_c0
• Git worktree docs: https://git-scm.com/docs/git-worktree

Before we start, here’s a link to one of the best free books on Git: Pro Git Book

What is Version Control?

When working on a project, we often need to keep track of changes made to the code. Version control systems help us track and reconcile changes across different versions of our codebase.

Think of your codebase as a tree. Each change you make can create a new branch in the tree. It’s up to you to decide if your changes are good enough to become part of the main branch. But why a tree? Because we have a single source of truth (the main branch) based on which we can reconcile all changes.

Imagine the source of truth is a single branch called main. When you want to work on a new feature, you create a branch from main, make your changes in that branch, and once you’re done, you can merge the branch back into main.

This approach allows us to:

1. Work on multiple features in parallel
2. Enable multiple people to work on the same codebase simultaneously
3. Revert to previous stable states if something goes wrong

Getting Started

First, download Git from here and install it.

In this guide, we’ll cover:

1. Setting up Git credentials
2. Creating a new repository
3. Understanding the staging area and making commits
4. Working with branches
5. Merging branches
6. Working with remote repositories
7. Common Git commands and workflows

1. Setting Up Git Credentials

Before you start using Git, configure your name and email. These will be associated with all your commits.

1git config --global user.name "Your Name"
2git config --global user.email "your.email@example.com"

You can verify your configuration with:

1git config --list

2. Creating a New Repository

Navigate to the directory where you want to create the repository. You can either:

• Initialize an existing directory as a Git repository
• Create a new directory and then initialize it

1# Option 1: Initialize current directory
2git init
3
4# Option 2: Create new directory and initialize
5mkdir my-project
6cd my-project
7git init

3. Understanding the Staging Area and Making Commits

Git uses a three-stage workflow:

1. Working Directory: Your files as they exist on disk
2. Staging Area: Files you’ve marked to be included in the next commit
3. Repository: Committed snapshots of your project

Let’s create a file and commit it:

1# Create a new file
2echo "Hello, World!" > hello.txt
3
4# Stage the file (add it to the staging area)
5git add hello.txt
6
7# Commit the changes with a descriptive message
8git commit -m "Add hello.txt file"

Key Commands:

• git status - See which files are modified, staged, or untracked
• git add <file> - Stage a specific file
• git add . - Stage all changes in the current directory
• git commit -m "message" - Commit staged changes with a message

4. Working with Branches

Branches allow you to work on features, experiments, or fixes without affecting the main codebase.

Create and switch to a new branch:

1git checkout -b feature1

This is equivalent to:

1git branch feature1      # Create the branch
2git checkout feature1    # Switch to the branch

Modern alternative (Git 2.23+):

1git switch -c feature1   # Create and switch

Make changes in the new branch:

1echo "Hello, World! in feature1" > hello.txt

View all branches:

1git branch                # List local branches
2git branch -a            # List all branches (local and remote)

5. Committing Changes to a Branch

1git add hello.txt
2git commit -m "Update hello.txt in feature1 branch"

6. Merging Branches

Once your feature is complete, merge it back into main:

1# Switch back to main branch
2git checkout main
3
4# Merge feature1 into main
5git merge feature1

Note: If there are no conflicts, Git will automatically create a merge commit. If conflicts occur, you’ll need to resolve them manually.

7. Working with Remote Repositories

Remote repositories allow you to collaborate with others and back up your code.

Add a remote repository:

First, create a new repository on a platform like GitHub, GitLab, or Bitbucket. Then copy the repository URL and add it as a remote:

1git remote add origin <remote-repository-URL>

View remote repositories:

1git remote -v              # List all remotes with URLs

Update remote URL (if needed):

1git remote set-url origin <new-URL>

8. Pushing Changes to Remote

Push your local commits to the remote repository:

1git push -u origin main

The -u flag sets up tracking, so future pushes can be done with just git push.

Push to a specific branch:

1git push origin feature1

9. Pulling Changes from Remote

git pull fetches changes from the remote and merges them into your current branch:

1git pull origin main

Note: git pull is equivalent to git fetch followed by git merge.

10. Fetching Changes from Remote

git fetch downloads changes from the remote without merging them:

1git fetch origin

This is useful when you want to see what changes exist on the remote before merging them. After fetching, you can review changes with:

1git log origin/main..main    # See commits on remote
2git diff origin/main          # See differences

Additional Useful Commands

Viewing History and Changes

1git log                      # View commit history
2git log --oneline            # Compact one-line view
3git log --graph --oneline    # Visual branch history
4git diff                     # See unstaged changes
5git diff --staged            # See staged changes
6git show <commit-hash>       # Show details of a specific commit

Undoing Changes

1git restore <file>           # Discard changes in working directory
2git restore --staged <file>  # Unstage a file
3git reset HEAD~1             # Undo last commit (keeps changes)
4git reset --hard HEAD~1      # Undo last commit (discards changes) - use with caution!

Working with .gitignore

Create a .gitignore file to exclude files from version control:

1# Example .gitignore
2node_modules/
3*.log
4.env
5.DS_Store

Cloning a Repository

To get a copy of an existing repository:

1git clone <repository-URL>

This creates a new directory with the repository name and downloads all files and history.

Common Workflows

Typical workflow:

1. git pull - Get latest changes
2. git checkout -b feature-name - Create feature branch
3. Make changes and git add files
4. git commit -m "message" - Commit changes
5. git push origin feature-name - Push to remote
6. Create pull/merge request on platform
7. After review, merge to main
8. git checkout main && git pull - Update local main

Tips and Best Practices

1. Write clear commit messages: Describe what and why, not how
2. Commit often: Small, logical commits are easier to review and revert
3. Pull before push: Always pull latest changes before pushing
4. Use branches: Keep main stable, work on features in branches
5. Review before merging: Check your changes with git diff and git status

Intuition

The problem is asking us to generate the gray code for a given number n.

Gray code is a binary numeral system where two successive values differ in only one bit. This is similar to bit strings problem. But instead of printing the binary representation of the number, we need to print the gray code.

The formula to generate the gray code for a given number n is:

Solution

1def main():
2    n = int(input())
3    for i in range(2**n):   
4        num = i^(i>>1)
5        num_str = bin(num)[2:].zfill(n)
6        print(num_str, end="\n")
7
8if __name__ == "__main__":
9    main()

Other possible solutions

Bit-by-Bit Approach

This approach constructs the Gray code by calculating each bit position individually using the property that the i-th bit of the Gray code is the XOR of the i-th and (i+1)-th bits of the binary representation.

Dry Run for n = 2

For n = 2, we need to generate 4 Gray codes (2² = 4). Let’s walk through each iteration:

Iteration 1: i = 0

• Binary representation: 00
• Bit position 0 (rightmost):
  • Current bit: (0 » 0) & 1 = 0 & 1 = 0
  • Next bit: (0 » 1) & 1 = 0 & 1 = 0 (since bit position 1 < n=2)
  • Gray bit: 0 ⊕ 0 = 0
  • Set bit: gray = 0 | (0 « 0) = 0
• Bit position 1:
  • Current bit: (0 » 1) & 1 = 0 & 1 = 0
  • Next bit: 0 (since bit position 2 >= n=2)
  • Gray bit: 0 ⊕ 0 = 0
  • Set bit: gray = 0 | (0 « 1) = 0
• Result: 00

Iteration 2: i = 1

• Binary representation: 01
• Bit position 0:
  • Current bit: (1 » 0) & 1 = 1 & 1 = 1
  • Next bit: (1 » 1) & 1 = 0 & 1 = 0
  • Gray bit: 1 ⊕ 0 = 1
  • Set bit: gray = 0 | (1 « 0) = 1
• Bit position 1:
  • Current bit: (1 » 1) & 1 = 0 & 1 = 0
  • Next bit: 0 (since bit position 2 >= n=2)
  • Gray bit: 0 ⊕ 0 = 0
  • Set bit: gray = 1 | (0 « 1) = 1
• Result: 01

Iteration 3: i = 2

• Binary representation: 10
• Bit position 0:
  • Current bit: (2 » 0) & 1 = 2 & 1 = 0 (2 in binary is 10, rightmost bit is 0)
  • Next bit: (2 » 1) & 1 = 1 & 1 = 1
  • Gray bit: 0 ⊕ 1 = 1
  • Set bit: gray = 0 | (1 « 0) = 1
• Bit position 1:
  • Current bit: (2 » 1) & 1 = 1 & 1 = 1
  • Next bit: 0 (since bit position 2 >= n=2)
  • Gray bit: 1 ⊕ 0 = 1
  • Set bit: gray = 1 | (1 « 1) = 1 | 2 = 3
• Result: 11

Iteration 4: i = 3

• Binary representation: 11
• Bit position 0:
  • Current bit: (3 » 0) & 1 = 3 & 1 = 1 (3 in binary is 11, rightmost bit is 1)
  • Next bit: (3 » 1) & 1 = 1 & 1 = 1
  • Gray bit: 1 ⊕ 1 = 0
  • Set bit: gray = 0 | (0 « 0) = 0
• Bit position 1:
  • Current bit: (3 » 1) & 1 = 1 & 1 = 1
  • Next bit: 0 (since bit position 2 >= n=2)
  • Gray bit: 1 ⊕ 0 = 1
  • Set bit: gray = 0 | (1 « 1) = 2
• Result: 10

Final Gray Code Sequence: 00, 01, 11, 10

Notice how each consecutive Gray code differs by only one bit:

• 00 → 01 (bit 0 changes: 0→1)
• 01 → 11 (bit 1 changes: 0→1)
• 11 → 10 (bit 0 changes: 1→0)

 1def generate_gray_code_bitwise(n):
 2    result = []
 3    for i in range(2**n):
 4        gray = 0
 5        for bit in range(n):
 6            # Gray bit is XOR of current bit and next bit
 7            current_bit = (i >> bit) & 1 # this step get the current bit using bitwise shift and bitwise and
 8            next_bit = (i >> (bit + 1)) & 1 if bit + 1 < n else 0 # this step get the next bit using bitwise shift and bitwise and
 9            gray_bit = current_bit ^ next_bit # this step get the gray bit using bitwise xor
10            gray |= (gray_bit << bit) # this step set the gray bit using bitwise or
11        result.append(bin(gray)[2:].zfill(n))
12    return result
13
14def main():
15    n = int(input())
16    gray_codes = generate_gray_code_bitwise(n)
17    for code in gray_codes:
18        print(code)
19
20if __name__ == "__main__":
21    main()

Intuition

Problem is asking us to find the number of combinations of 0s and 1s of length n. Basically its 2^n combinations.

Solution

1def main():
2    n = int(input())
3    print(2**n % 1000000007)
4
5if __name__ == "__main__":
6    main()

In python it feels cheating to use the power operator **, but it is a valid way to solve the problem.

In lower level languages like C, C++, Java, we need to use a loop to calculate the power of 2 and each time we take modulo 1e9+7.

 1#include <stdio.h>
 2#include <stdlib.h>
 3
 4int main() {
 5    int n;
 6    scanf("%d", &n);
 7    long long result = 1;
 8    for(int i = 0; i < n; i++) {
 9        result = (result * 2) % 1000000007;
10    }
11    printf("%lld\n", result);
12    return 0;
13}

Intuition

The problem asking us to partition the given set of numbers into two sets such that the sum of the numbers in the two sets are equal.

For the sum of two sets to be equal the total sum of the numbers must be even. That means sum(numbers) % 2 == 0. by the forumla for the sum of the first n natural numbers, sum(numbers) = n * (n + 1) / 2. So that means sum of each set must be n * (n + 1) / 4.

Hence we got that n mod 4 is 0 or (n+1) mod 4 is 0, combining both we get n mod 4 must be 0 or 3 to be able to partition the numbers into two sets. So this becomes a necessary condition for the problem to be solvable.

but this is not a sufficient condition.

When n mod 4 = 0: Total sum is even, partition is possible. The set can be split so both subsets have the same number of elements (equal size).

Example: n=8

Pairs: (8,1), (7,2), (6,3), (5,4)

Assign two pairs to one set, the other two pairs to the other set—both sum to 18.

When n mod 4 = 3: Total sum is even, partition is possible.

The sets will have different sizes (one will have one more element). Example: n=7

Pairs: (7,1,6) sums to 14, rest (2,3,4,5) sum to 14.

The sum of each smallest–largest pair is always n+1.

For n mod 4 = 0: you can split pairs alternately between the two sets.

For n mod 4 = 3: this is a tricky case Consider some integer k such that we have n = 4k+3. that means n mod 4 = 3. Now sum of n numbers is n * (n + 1) / 2 = (4k+3) * (4k+4) / 2 = (4k+3) * (2k+2)

Mathematical Derivation

For n = 4k + 3, we assign:

• Set 1: numbers where i ≡ 1 or 2 (mod 4)
• Set 2: numbers where i ≡ 0 or 3 (mod 4)

Count of numbers in each residue class:

• ≡ 0 mod 4: k numbers (4, 8, …, 4k)
• ≡ 1 mod 4: k+1 numbers (1, 5, …, 4k+1)
• ≡ 2 mod 4: k+1 numbers (2, 6, …, 4k+2)
• ≡ 3 mod 4: k+1 numbers (3, 7, …, 4k+3)

Sum of each residue class:

≡ 0 mod 4:

4 + 8 + ... + 4k = 4(1 + 2 + ... + k) = 4 × k(k+1)/2 = 2k(k+1)

≡ 1 mod 4:

1 + 5 + 9 + ... + (4k+1)

Arithmetic series: first term = 1, last term = 4k+1, common difference = 4, terms = k+1

Sum = (k+1) × (1 + 4k+1)/2 = (k+1) × (4k+2)/2 = (k+1) × 2(k+1) = 2(k+1)²

≡ 2 mod 4:

2 + 6 + 10 + ... + (4k+2)

Arithmetic series: first term = 2, last term = 4k+2, common difference = 4, terms = k+1

Sum = (k+1) × (2 + 4k+2)/2 = (k+1) × (4k+4)/2 = (k+1) × 2(k+2) = 2(k+1)(k+2)

≡ 3 mod 4:

3 + 7 + 11 + ... + (4k+3)

Arithmetic series: first term = 3, last term = 4k+3, common difference = 4, terms = k+1

Sum = (k+1) × (3 + 4k+3)/2 = (k+1) × (4k+6)/2 = (k+1) × 2(k+3) = 2(k+1)(k+3)

Total sum verification:

Total sum = 2k(k+1) + 2(k+1)² + 2(k+1)(k+2) + 2(k+1)(k+3)
         = 2(k+1) × [k + (k+1) + (k+2) + (k+3)]
         = 2(k+1) × (4k + 6)
         = 2(k+1) × 2(2k + 3)
         = 4(k+1)(2k + 3)

Each set should sum to: 2(k+1)(2k + 3)

Sum of each set:

Set 1 (≡1 or ≡2 mod 4):

Sum = 2(k+1)² + 2(k+1)(k+2) = 2(k+1) × [(k+1) + (k+2)] = 2(k+1) × (2k + 3)

Set 2 (≡0 or ≡3 mod 4):

Sum = 2k(k+1) + 2(k+1)(k+3) = 2(k+1) × [k + (k+3)] = 2(k+1) × (2k + 3)

Both sets sum to 2(k+1)(2k + 3), which is exactly half the total sum.

Solution

 1def main():
 2    n = int(input())
 3    if n % 4 not in (0, 3):
 4        print("NO")
 5        return
 6    
 7    set1 = []
 8    set2 = []
 9    toggle = True
10    
11    if n % 4 == 0:
12        low = 1
13        high = n
14        while low <= high:
15            if toggle:
16                set1.append(low)
17                set1.append(high)
18            else:
19                set2.append(low)
20                set2.append(high)
21            low += 1
22            high -= 1
23            toggle = not toggle
24    else:
25        for i in range(1, n+1):
26            if i % 4 == 1 or i % 4 == 2: # 
27                set1.append(i)
28            else:
29                set2.append(i)
30    
31    # Output the result
32    print("YES")
33    print(len(set1))
34    print(" ".join(map(str, set1)))
35    print(len(set2))
36    print(" ".join(map(str, set2)))
37
38if __name__ == "__main__":
39    main()

Intuition

The idea is to generate a permutation of the numbers from 1 to n such that the difference between any two consecutive elements is at least greater than 1.

One way to do this is to first write all the even numbers between 1 and n in increasing order and then write all the odd numbers between 1 and n in increasing order.

This is only one such solution. There are other solutions as well.

Edge case:

• If n is 1, print 1. this is because there are no consecutive elements in the permutation, hence is a valid permutation.
• If n is less than 4, print “NO SOLUTION”. because for n < 4, any permutation will have a difference between any two consecutive elements less than 1. example 1 2 3 4, 1 3 2 4, 1 3 4 2, etc are not valid permutations.

Solution

 1def main():
 2    n = int(input())
 3    if n == 1:
 4        print(1)
 5        return
 6    if n < 4:
 7        print("NO SOLUTION")
 8        return
 9    for i in range(2,n+1,2):
10        print(i, end=" ")
11    for i in range(1,n+1,2):
12        print(i, end=" ")
13
14if __name__ == "__main__":
15    main()

Other possible solutions

• Write all the odd numbers between 1 and n in increasing order and then write all the even numbers between 1 and n in increasing order.
• Write all the odd numbers between 1 and n in decreasing order and then write all the even numbers between 1 and n in decreasing order.
• Write all the even numbers between 1 and n in increasing order and then write all the odd numbers between 1 and n in decreasing order.

Intuition

The idea is to make an array increasing by making the current element equal to or greater than the previous element. and in each step we can increase the value of a single element by 1.

That means for ith element which is less than the i-1th element, we need elem[i-1] - elem[i] steps to make it equal to or greater than the i-1th element.

So we can come up with the following algorithm:

• Loop through the array
• If the current element is less than the previous element, we need to increase the current element to the previous element.
• Increment the count by the difference between the previous element and the current element.
• Update the current element to the previous element.

At the end of the loop, we will have the minimum number of steps to make the array increasing.

Solution

 1def main():
 2    n = int(input())
 3    nums = list(map(int, input().split()))
 4    count = 0
 5    for i in range(0,n-1):
 6        if nums[i] > nums[i+1]:
 7            count += nums[i] - nums[i+1]
 8            nums[i+1] = nums[i]
 9    print(count)
10
11if __name__ == "__main__":
12    main()

Mathematical Proof

Theorem: The greedy algorithm that ensures each element is at least as large as its predecessor gives the minimum total cost to make the array non-decreasing.

Proof by Induction:

Base Cases:

• For an array of size 1: The cost is 0, which is trivially optimal.
• For an array of size 2: If nums[0] ≤ nums[1], cost is 0. If nums[0] > nums[1], we must increment nums[1] by nums[0] - nums[1] to make it ≥ nums[0]. This is optimal since we must satisfy nums[1] ≥ nums[0].

Inductive Hypothesis: Assume the greedy algorithm is optimal for arrays of size ≤ k.

Inductive Step: Consider an array of size k+1. Let the array be a[0], a[1], ..., a[k].

Apply the greedy algorithm:

1. Process the first k elements optimally (by inductive hypothesis)
2. For the last element a[k], if a[k-1] ≤ a[k], no change needed (cost 0)
3. If a[k-1] > a[k], increment a[k] to a[k-1], costing a[k-1] - a[k]

Why this is optimal: Any optimal solution must satisfy a'[i] ≥ a'[i-1] for all i, where a' is the final array.

For the prefix a'[0] ... a'[k-1], the inductive hypothesis says our greedy choices give the minimum cost.

For the last pair a'[k-1] and a'[k]:

• We must have a'[k] ≥ a'[k-1]
• The minimum cost to achieve this is exactly max(0, a'[k-1] - a'[k])
• Our greedy algorithm achieves exactly this minimum cost

Key insight: The greedy choice doesn’t affect the optimality of the prefix because:

1. The prefix constraints are already satisfied optimally
2. Setting a[k] = max(a[k], a[k-1]) only affects the relationship between a[k-1] and a[k]
3. This choice is independent of future elements since there are none

Proof by Contradiction : Suppose there exists an optimal solution with lower total cost than the greedy algorithm. Let the greedy algorithm produce array g with cost C_g. Let the optimal solution produce array o with cost C_o < C_g.

Since both g and o must satisfy g[i] ≥ g[i-1] and o[i] ≥ o[i-1] for all i:

• At the first position where g and o differ, the optimal solution must have made a different choice
• But making a different choice would either violate the non-decreasing constraint or require more operations later, contradicting optimality

Therefore, the greedy algorithm is optimal.

Intuition

This problem wants us to find the longest substring of a string that has only 1 type of character. input has A,G,C and T only.

Edge case: if the string is empty, return 0.

We need to keep track of the current length of the substring and the maximum length of the substring seen so far which satisfies the condition.

Loop through the string and check if the current character is the same as the previous character.

• If it is, increment the current length. Update the maximum length if the current length is greater than the maximum length.
• If it is not, reset the current length to 1.

Solution

 1def main():
 2    string = input().strip()
 3    if not string:
 4        print(0)
 5        return
 6    
 7    max_len = 1
 8    current_len = 1
 9    
10    for i in range(1, len(string)):
11        if string[i] == string[i-1]:
12            current_len += 1
13            max_len = max(max_len, current_len)
14        else:
15            current_len = 1
16    
17    print(max_len)
18
19if __name__ == "__main__":
20    main()

Time complexity

O(n)

Space complexity

O(1)

This is a greedy problem. A greedy approach is something that makes the best local choice at each step in the hope that this choice will lead to the global optimal solution.

here the best local choice is to increment the current length if the current character is the same as the previous character.

Intuition

This problem wants us to find the missing number in a sequence of numbers from 1 to n. The naive approach is to use a hash map to store the numbers and then find the missing number. But this is not efficient.

The idea is to use the formula for the sum of an arithmetic series. The sum of an arithmetic series is given by the formula:

where n is the number of terms, a is the first term, and l is the last term. In this problem, the first term is 1 and the last term is n. So the sum of the series is given by the formula:

now if we accumulate the sum of the numbers in the list, we can find the missing number by subtracting the sum of the numbers in the list from the sum of the series. Since only one number is missing, the sum of the numbers in the list will be less than the sum of the series and the difference will be the missing number.

Solution

 1def main():
 2    n = int(input())
 3    nums_list = input().strip()
 4    nums = nums_list.split()
 5    total = 0
 6    for num in nums:
 7        total += int(num)
 8    tot = n * (n + 1) // 2
 9    print(tot - total)
10
11
12if __name__ == "__main__":
13    main()

Some formulae for arithmetic series

nth term

where a is the first term, d is the common difference, and n is the number of terms.

sum of the first n terms

where n is the number of terms, a is the first term, and l is the last term.

sum of the first n terms

where n is the number of terms, a is the first term, and d is the common difference.

Intuition

This problem is a direct implementation of the algorithm described in the problem statement.

Given a number n, we need to apply the following algorithm:

1. If n is even, divide it by 2.
2. If n is odd, multiply it by 3 and add 1.
3. Repeat the process until n becomes 1.

Solution

1def weird_algorithm(n):
2    while n != 1:
3        print(n, end=" ")
4        if n % 2 == 0:
5            n = n // 2
6        else:
7            n = 3 * n + 1
8    print(n)

Geek fact

This is a famous problem in the field math called the Collatz conjecture.

Collatz conjecture is a conjecture in mathematics that states that for any positive integer n, the sequence of numbers generated by the following algorithm will eventually reach 1.

So far, the conjecture has been verified for all positive integers up to 2^68.

Wikipedia link: Collatz conjecture

This is bold text, and this is emphasized text.

Visit the Hugo website!

Mathematical Examples

Here are some mathematical expressions rendered using LaTeX:

Inline Math

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

Display Math

The Pythagorean theorem:

More Complex Equations

The area of a circle:

Integration by parts:

Matrices

A simple 2x2 matrix:

Limits and Derivatives

Limit as x approaches infinity:

This is how code looks like

1print("Hello, World!")

This is a blockquote

This is a nested blockquote

This is a nested nested blockquote

This is how a table looks like

inline code

 1<!DOCTYPE html>
 2<html lang="en">
 3<head>
 4  <meta charset="UTF-8">
 5  <meta name="viewport" content="width=device-width, initial-scale=1.0">
 6  <title>Document</title>
 7</head>
 8<body>
 9  <h1>Hello, World!</h1>
10</body>
11</html>