DEV Community: Echo

Why I built a small desktop app to stop losing my Claude Code sessions

Echo — Wed, 03 Jun 2026 05:00:22 +0000

This is a builder note, not a launch post. I am writing it because the project is now at v0.2.18, and the question I keep getting asked in private is: why a desktop app, why Tauri, why not just a web app?

Here is the honest answer.

The trigger was small. I had twelve repos I was actively using Claude Code on. One afternoon I wanted to recover a session from three weeks ago, in a repo I had not touched in a month. I knew what I had asked the model to do. I did not know which of the twelve project folders under ~/.claude/projects/ the session lived in, and I did not remember the timestamp.

The session was technically on disk. I just could not find it. That gap (the data exists, but the index is missing) is what I wanted to close.

The first version of Shelf was 200 lines of Python and a SQLite table. It just listed every session in every project, sorted by mtime. I could grep the table. That alone was useful.

The current version is a Tauri app (Rust + WebView). The reason I switched from a CLI to a desktop app was not aesthetics. It was because the actual use case has three sub-tasks that are awkward on a terminal:

Scan, then show the result in a way that surfaces "this is the session that touched file X" without me having to open the JSONL.
One click to resume the session. Claude Code's CLI resume is fine if you know the id, but you never know the id.
Work on more than one project at once. The terminal is great for one project. It is bad at three.

Local, not cloud, was a deliberate choice. The session files contain everything I have ever typed into a model, including private notes about my own work. I do not want a server roundtrip just to read my own data. Tauri was the smallest path to a real desktop app I could ship and maintain myself.

If you have ever grepped ~/.claude/projects/*/*.jsonl and felt like that should not be the answer, the project is here: https://github.com/Harukaon/shelf. Pull it apart, tell me what is wrong, fork it, do not use it, all of the above.

Found a tool that finally organizes my Claude Code chaos

Echo — Wed, 03 Jun 2026 04:03:17 +0000

I have been using Claude Code for about ten months. The session organization story went something like this:

Month 1: I closed a long session by accident. Lost 40 minutes of context.
Month 3: I learned about /resume and /rename. Renamed every session I cared about.
Month 5: I had 60+ named sessions across 8 projects. I could not remember the names. /resume was useless.
Month 7: I started grepping ~/.claude/projects/*/*.jsonl. Worked, but I never knew which project folder to grep first.
Month 9: I just gave up and re-ran the work, slower.

The honest summary: Claude Code saves everything. The problem is it does not help me find anything.

I have tried the obvious things:

terminal scrollback (gone when I close the tab)
copying key bits to a "prompts" notes file (low fidelity)
search by project name in ~/.claude/projects/ (works but slow)
AGENTS.md and CLAUDE.md (good for future sessions, useless for past ones)

What I actually wanted: an indexed view of every session I ever ran, searchable by keyword, grouped by project, with one click to resume.

Two months ago I started using Shelf. It is a small Tauri desktop app (local, not cloud) that does exactly this: it scans ~/.claude/projects/ and ~/.codex/sessions/, shows you every session as a card, lets you search across them, and reopens the right one when you click. It also keeps a per-project view so I can see "what was I doing in repo X last week" without grepping.

Is it perfect? No. The startup scan is slow if you have a lot of sessions. The UI is functional, not beautiful. But it is the first thing I have used that actually matches the mental model I had for "find me the conversation where I solved Y".

If your Claude Code history is more than a handful of weeks deep, you have probably already felt the pain. I would be curious what other people are doing.

Tags: claudecode, codex, productivity, devtools, opensource

Three Small CLI Tools I Built to Make Claude Code Feel Less Like a Black Box

Echo — Tue, 02 Jun 2026 15:10:53 +0000

Three Small CLI Tools I Built to Make Claude Code Feel Less Like a Black Box

The most common complaint I hear from teammates trying Claude Code for the first time is not "the model is bad". It is "I do not know what the model is doing". The session is opaque — a long scrollback of edits, reads, and bash calls, with no way to skim it or to see at a glance where the last 30 minutes went.

I built three small CLI tools to fix that. None of them are clever. All of them are under 200 lines. The first one I should have built years ago.

1. `cc-tail` — stream the last N tool calls

The first thing every new Claude Code user wants is a way to see the recent activity. The scrollback is too long to read every time, and the inline UI does not give a summary view. So I wrote a 50-line script that tails the JSONL log under ~/.claude/projects/:

#!/usr/bin/env bash
# cc-tail — show the last N tool calls from the active project
N="${1:-10}"
LATEST=$(ls -t ~/.claude/projects/*/*.jsonl 2>/dev/null | head -1)
[ -z "$LATEST" ] && { echo "no session log"; exit 1; }
tail -n "$N" "$LATEST" | python3 -c '
import sys, json
for line in sys.stdin:
    try:
        e = json.loads(line)
        t = e.get("type", "")
        if t == "tool_use":
            name = e.get("name", "?")
            inp = e.get("input", {})
            arg = inp.get("file_path") or inp.get("command") or str(inp)[:60]
            print(f"[{e.get(\"timestamp\",\"\")[:19]}] {name}: {arg}")
        elif t == "user":
            content = e.get("message", {}).get("content", "")
            if isinstance(content, str):
                print(f"[{e.get(\"timestamp\",\"\")[:19]}] user: {content[:80]}")
    except Exception:
        pass
'

Run it as cc-tail 20 and you get a readable trace of the last 20 events. It is the difference between "I think the model is doing something weird" and "ah, it is grepping for the wrong path".

2. `cc-cost` — session cost by project

The Anthropic API returns token counts; the CLI shows them per turn. I wanted the session total, grouped by project. So:

#!/usr/bin/env bash
# cc-cost — total cost of the current Claude Code session
LATEST=$(ls -t ~/.claude/projects/*/*.jsonl 2>/dev/null | head -1)
python3 -c "
import json
in_t = out_t = cache_r = cache_w = 0
with open('$LATEST') as f:
    for line in f:
        try: e = json.loads(line)
        except: continue
        u = e.get('message', {}).get('usage', {})
        in_t += u.get('input_tokens', 0)
        out_t += u.get('output_tokens', 0)
        cache_r += u.get('cache_read_input_tokens', 0)
        cache_w += u.get('cache_creation_input_tokens', 0)
# Sonnet 4.6 numbers as of writing
cost = in_t*3e-6 + out_t*15e-6 + cache_r*3e-7 + cache_w*3.75e-6
print(f'in: {in_t:,}  out: {out_t:,}  cache_r: {cache_r:,}  cache_w: {cache_w:,}')
print(f'approx cost: \${cost:.2f}')
"

It is approximate. The point is that it is honest. After running it once you stop guessing and start noticing which sessions are the expensive ones.

3. `cc-where` — where did the model touch the file system?

Most regressions I have debugged were not "the model wrote the wrong code". They were "the model wrote the right code in the wrong place". A 30-line cc-where:

#!/usr/bin/env bash
# cc-where — list the unique file paths the latest session touched
LATEST=$(ls -t ~/.claude/projects/*/*.jsonl 2>/dev/null | head -1)
grep -oE '"file_path":"[^"]+"' "$LATEST" | sort -u

That is the whole tool. Pipe it through wc -l and you get a number; pipe it through xargs -I{} sh -c 'echo "$(git log -1 --format=%h {}) {}"' and you get a useful audit.

What these tools do not do

They do not write to the session, do not change the model, do not require API keys. They are pure observers over the existing JSONL log. That is the point — most "Claude Code is opaque" complaints are really "I do not have a small read-only tool over the data that is already on disk". Once you have one, the opacity goes away.

The hard part is the JSONL format is technically internal and changes between versions. These tools break once a quarter, and I rewrite them in 10 minutes when that happens. Worth it.

Tags: claudecode, codex, cli, devtools, observability, ai

Three PreToolUse Hooks I Stopped Using (and What Replaced Them)

Echo — Tue, 02 Jun 2026 13:38:11 +0000

Three PreToolUse Hooks I Stopped Using (and What Replaced Them)

I have rolled out a lot of PreToolUse hooks over the last six months. Most of them were a mistake. Here are the three I removed and what I actually use now.

1. "Don't edit files outside the project" hooks

The hook would inspect file_path in the Edit tool's arguments, check that it started with the project root, and short-circuit if it didn't. The intent was good — Claude Code does occasionally wander into ~/.zshrc if you let it — but the implementation was wrong.

The cost was high: every single Edit, Read, Write, and Bash call paid the hook's regex + path check, even on the 99% of cases that were fine. The benefit was rare, and when it did fire, the model would just retry with a different path. The hook trained the model to be sneaky about file paths instead of being honest about wanting to touch them.

What replaced it: a one-line rule in CLAUDE.md that says "ask before editing anything outside this project's tree" and a SessionStart hook that prints the project root. The model has the rule, the session knows the boundary, and the per-call cost is zero.

2. "Strip secrets from tool output" hooks

This one looked important on paper. The PostToolUse hook would grep the tool result for sk-, AKIA, and other secret patterns and redact them. The model would then see [REDACTED] and behave accordingly.

The cost was even worse than the file-scope hook. A PostToolUse hook runs on every Bash, Read, and Edit result. The secret scanner did a regex over potentially huge outputs, and most of the work was wasted because no secret was actually there. When a real secret was in a log dump, the redaction usually happened on the wrong line — the secret was a few characters past where the regex stopped.

What replaced it: a .gitignore that includes .env* plus a SessionStart hook that does a one-time git log --diff-filter=A --name-only to make sure no .env ever got committed in the first place. The model never sees the secret because it never tries to read it. The per-call cost is zero, and the redaction is correct because there is no redaction to do.

3. "Inject project context on every Read" hooks

The intent was to give the model a per-file "this file is part of the auth module, treat it carefully" comment on every Read call. The hook would do a quick git log and file-glob lookup and prepend a small context block to the tool output.

The cost was the highest of the three. Reads are the most frequent tool call in a long session, and the git log would itself trigger a Bash call on some setups, leading to recursive hook runs that I had to debug more than once. The benefit was marginal because the model rarely uses injected context when it appears in the middle of a file read — it focuses on the file content and ignores the prefix.

What replaced it: a project-level .claude/docs/ directory of short canonical notes, and a SessionStart hook that lists the available notes. The model reads the relevant note on demand, and the cost is one bash call per session, not one per Read.

What I still use

I kept two kinds of hooks:

SessionStart hooks for environment checks (preflight, arch lint, dependency availability). They run once per session, the cost is amortized, and the failure mode is "session starts broken" instead of "model writes a bad line of code".
PreToolUse hooks for destructive Bash commands — a tiny allowlist check for rm -rf, git push --force, kubectl delete. The cost is one regex per Bash, the benefit is a hard stop on a class of mistakes that no prompt can reliably prevent.

Everything else I tried was a hook for a problem that was better solved with a CLAUDE.md rule, a SessionStart script, or just letting the model do the work and trusting it.

Tags: claudecode, codex, hooks, devtools, ai

Why I Keep a Per-Project Investigation Log Outside Claude Code

Echo — Tue, 02 Jun 2026 12:30:08 +0000

Why I Keep a Per-Project Investigation Log Outside Claude Code

After about six months of running Claude Code across multiple repos, I have stopped pretending that conversation history is enough.

I still use Claude Code for almost everything. The in-conversation layer is excellent for "what should I do next" and "explain this error". The problem is what happens after the conversation ends: I close the session, switch projects, come back two days later, and I cannot find the investigation I am sure I did.

I tried three fixes, and the one that stuck is a per-project investigation log that lives outside the chat.

The first attempt: rely on /resume and session IDs.

The problem was remembering the session ID. By the time I needed the old conversation, I had forgotten the project name, the date, the symptom, and the keyword that would distinguish it from the eleven other sessions I ran that week. /resume works perfectly when you know what you are looking for. It does not help when the whole point of the search is "what was the keyword".

The second attempt: dump important findings into CLAUDE.md.

The problem was that CLAUDE.md is for behavior the model should follow every run. A "we tried plan B, plan A was faster because of X" note does not belong in a file the model reads on every session start. The signal-to-noise ratio collapses within a month, and the file becomes a graveyard of one-off decisions. I had to admit that CLAUDE.md is a constitution, not a journal.

The third attempt: a per-project investigation log, written by hand, indexed by project.

The format is a single markdown file per project, with one short entry per "investigation": a problem, the path I took, the conclusion, and any links or commit hashes. I append to it from a tiny shell command, so writing an entry takes five seconds. I read it whenever I am about to start work on the project, the way I would read a colleague's handover note.

The crucial detail is the indexing. Entries are filed by project, not by tool. If I had used the "Claude Code session browser" route, the same investigation under Cursor or Codex would have been filed under a different tool, and the cross-tool lookups would still break. The project is the unit of search.

What goes in:

A one-line summary of the question.
The decision I made and why.
A link to the commit, the PR, or the conversation (if I remember it).
Anything I want future-me to know — "don't redo this analysis, the bottleneck is in module X".

What stays out:

Anything that belongs in CLAUDE.md (rules the model must follow every run).
Long code excerpts. Paste a path and a line range instead.
Anything private to one session. If it is not useful next month, it is not useful.

The cheapest version of this is one markdown file per project, kept next to the code, with a short shell alias for appending. The richer version is a tool with a search box and a per-project filter. Both work. The richer one is what I am building as Shelf, because the manual approach broke down around eight projects.

If you only have two or three projects, the manual approach is fine. The shell alias is two lines. The discipline is "write the entry the moment you decide", not "I will remember to do it later". You will not.

Tags: claudecode, codex, devtools, productivity, workflow

Shelf, the open-source desktop workspace we are building around Claude Code and Codex, is the project-level retrieval layer we use to find old investigations by project. The link is at
https://github.com/Harukaon/shelf if you want to compare it to your current workflow.

Subagents vs Hooks in Claude Code: Picking the Right Tool for the Right Job

Echo — Tue, 02 Jun 2026 11:29:00 +0000

Subagents vs Hooks in Claude Code: Picking the Right Tool for the Right Job

The Claude Code subagent and the Claude Code hook look similar at a glance — both let you add "behavior the model should follow" — but they answer different questions, and using the wrong one is one of the most common ways teams end up with a sprawling CLAUDE.md and a slow, leaky workflow.

A short way to remember the difference:

Subagent = "do a separate scoped task and hand the result back." It is a worker with its own context, its own tool set, and a clean return path. It is good when the work is parallelizable or expensive to run inline.
Hook = "before/after this tool call, do something." It is a wrapper around the model's tool use. It is good when the work is invariant enforcement — the same prep or cleanup every time.

Five questions to pick the right one for any new behavior you want to add:

Does the work need a different context? If yes, subagent.
Does the work need different tools (or sandboxing)? If yes, subagent.
Is the trigger "the model called a tool"? If yes, hook.
Is the work about enforcing a constraint the user can forget (formatting, file scope, secrets)? If yes, hook.
Is the work about producing something the main thread will use? If yes, subagent.

Things that look like subagents but should be hooks:

"Always run pnpm format after every Edit." Hook.
"Always run the test suite before declaring done." Hook.
"Always run git status before any commit." Hook.

Things that look like hooks but should be subagents:

"Summarize a long PDF and put the summary in the chat." Subagent — it needs different tools and its own context.
"Run a 5-step research plan in parallel and combine the answers." Subagent.
"Find every place in the repo that uses a deprecated API." Subagent.

The place teams go wrong is using a hook to do a subagent's job. A "summarize this PDF" hook ends up reading the PDF inline in the main thread, blowing the context, and the user gets the first part of the summary truncated. Move it to a subagent and the main thread gets a clean pointer, and the summary can be a 200k-token scratchpad without polluting the per-run context.

The other way teams go wrong is using a subagent to do a hook's job. A "format the file after every edit" subagent that is invoked conditionally is the same job as a hook, but it is unreliable: the model can forget to invoke it, and the model can decide to skip the invocation. The hook runs deterministically, every time, on the tool event, not on the model's memory.

A good rule of thumb: if you find yourself writing "always remember to …" in CLAUDE.md, it is probably a hook. If you find yourself writing "sometimes ask X to do Y", it is probably a subagent.

Both pieces are part of the same toolbox. The forcing function for picking the right one is: what would happen if the model forgot? If the answer is "a small but consistent formatting bug", that's a hook's job. If the answer is "the model re-does an hour of work in the main thread", that's a subagent's job.

Shelf, the open-source desktop workspace we are building around Claude Code and Codex, is the project-level retrieval layer we use to find old sessions by project. The link is at
https://github.com/Harukaon/shelf if you want to compare it to your current workflow.

Tags: claudecode, codex, devtools, subagents, hooks, ai

CLAUDE.md as a Forcing Function: How Writing a Project Constitution Cleans Up Your Tooling

Echo — Tue, 02 Jun 2026 10:28:32 +0000

CLAUDE.md as a Forcing Function: How Writing a Project Constitution Cleans Up Your Tooling

If you have been using Claude Code for a few months across multiple repos, the cheap, ongoing mistake is to keep
adding rules to CLAUDE.md every time the model does something wrong. The list grows, the file becomes a copy
of a prompt template, and the model treats it like static noise.

A more useful pattern that has worked for our team: write CLAUDE.md as a constitution, not a prompt,
and use the constraint itself as a forcing function for cleaning up the underlying tools.

The mental shift is small but practical. Instead of "Claude keeps running the wrong test command, so add
a paragraph explaining how to run tests", write "the test command for this repo is pnpm test <name>",
and ask yourself: why is the test command even ambiguous? If the only way to explain it is a paragraph,
the tooling is the problem, not the prompt.

Three rules we follow:

Hard scope, positive form. A line that says "only edit files inside src/<module>/ and
tests/<module>/. Stop and ask if a change touches anything else" is more reliable than a list of
"never touch X" rules. Negative-form rules invite the model to find creative workarounds; positive
rules give it a default and an escalation path.
Short or it is wrong. A long CLAUDE.md is a symptom that the team is not investing in
package.json scripts, internal CLIs, and clear conventions. We cap the file around 2-3KB of
bullet points. Anything bigger is a hint that a tool needs to be wrapped in a script with a sane
surface area, not explained in markdown.
Memory and retrieval are not CLAUDE.md jobs. CLAUDE.md is for behavior that should apply
every run (build commands, lint scope, project layout). Past-decision context, code-archaeology
notes, and "what did I do last week" questions belong to a separate layer — git, a project
notebook, or, in our case, a local session retrieval tool. Mixing them in CLAUDE.md makes the
file grow and pollutes the per-run context window.

We did not start out with these rules. We arrived at them after watching CLAUDE.md files balloon
to 30KB and watching Claude ignore half of what we wrote. The cleanest side effect is that the team
also started writing better internal CLIs. When your constitution forces you to express a workflow
in one bullet, you cannot hide behind prose.

If you are just starting with Claude Code, my suggestion is to begin with a deliberately short
CLAUDE.md, watch what the model gets wrong, and let the file stay small. Long CLAUDE.md files
are a sign that the project itself needs more structure, not that the model needs more instructions.

Shelf, the open-source desktop workspace we are building around Claude Code and Codex, is the
project-level retrieval layer we use to find old sessions by project. The link is at
https://github.com/Harukaon/shelf if you want to compare it to your current workflow.

Tags: claudecode, codex, devtools, workflow, ai

From Terminal Tabs to Project Workspaces: How I Organize Claude Code and Codex Sessions

Echo — Tue, 02 Jun 2026 07:22:58 +0000

From Terminal Tabs to Project Workspaces: How I Organize Claude Code and Codex Sessions

I used to manage my AI coding sessions like browser tabs. Open Claude Code in a directory, chat for an hour, switch to another project, come back tomorrow, and... where was I?

The built-in /resume shows a flat list. /continue only works if I remember the session ID. After three months of daily Claude Code and Codex use, I had thirty-plus sessions scattered across six repositories, and zero confidence that I could find the conversation where I debugged that auth issue last Tuesday.

This isn't a Claude Code problem. It's a workspace problem.

What I actually needed

Not a better prompt. Not a bigger context window. I needed:

Project-level grouping — All sessions for backend-api in one place, all sessions for mobile-app in another.
Session discovery — A search that actually works across projects, not just within the current directory.
One-click recovery — Open a previous session without typing /resume and scrolling through a chronological dump.

What I built

I ended up writing a small desktop app called Shelf. It's a Tauri-based workspace manager that sits next to my terminal and tracks every Claude Code and Codex session by project.

Key things it does:

Scans ~/.claude/projects/ and ~/.codex/ automatically and groups sessions by git repository.
Lists every conversation with a preview of the last few turns, so I can spot "the auth debugging session from Tuesday" without opening it.
Restores any session in its original working directory with one click.
Embedded terminal — I can open a PTY right inside the app if I just want to check a log without launching Claude Code.

It's not trying to replace Claude Code or Codex. It's just the missing workspace layer.

Architecture notes (for the curious)

Tauri v2 + Rust for the backend file scanning and session restoration.
TypeScript + Vite for the UI.
xterm.js for the embedded terminal.
Cross-platform: macOS (Apple Silicon) and Linux.

The habit change

The biggest shift wasn't technical. It was mental. I stopped treating each Claude Code session as disposable. Now I name my sessions intentionally, close them cleanly, and trust that I can get back to any project's state within ten seconds.

If you're juggling multiple repos with Claude Code or Codex, the tool is at https://github.com/Harukaon/shelf. It's open source, v0.2.18, and I'd genuinely appreciate feedback or PRs.

What does your Claude Code workspace look like? Still using terminal tabs, or have you found something else that works?

Five Claude Code habits that cost nothing and save hours

Echo — Tue, 02 Jun 2026 06:05:19 +0000

I have been using Claude Code daily for about a year across multiple repos. These five habits are free, require no plugins, and have saved me more time than any model upgrade.

1. Name your sessions immediately

The default session names are "task-abc123" or "fix-xyz". After three days you have no idea what was in there. The fix is trivial: start every session with a one-line summary.

Bad: claude -> default name task-2026-06-02-abc123
Good: claude -> say "Refactor auth module token validation logic" -> session name is now descriptive

When you run /resume a week later, you will actually know which session to pick.

2. Treat CLAUDE.md as a correction log, not a spec

Most people write CLAUDE.md once and forget it. The better approach is to append a rule every time Claude makes a repeatable mistake.

Examples from my current project:

"Always use pnpm in this repo. Do not generate package-lock.json."
"API response keys must be camelCase."
"Integration tests need a local Redis instance."

Each rule is a single sentence. The file grows organically and future sessions inherit it automatically.

3. Know the difference between /continue and /resume

/continue (or claude --continue): reopens the most recent session in the current directory. Use this when you stopped working yesterday and want to pick up where you left off.
/resume (or claude --resume): opens a picker of all historical sessions. Use this when you need a specific older conversation.

The trap is that /resume only helps if you remember the session name or ID. After a few repos and dozens of sessions, the flat list becomes useless.

4. Export decisions before they disappear

When a session contains a design decision, architectural choice, or complex debugging path, run /export before closing it. The output is a markdown file you can drop into your project docs.

The alternative is digging through ~/.claude/projects/ raw JSONL files later. Those files contain everything, but they are not meant for human reading.

5. Separate memory from retrieval

This is the habit that took me longest to learn.

Memory = reusable facts that future sessions need (CLAUDE.md, rules, conventions).
Retrieval = finding the old session that actually contained the decision.

CLAUDE.md handles memory well. Retrieval is harder because Claude Code's native tools are designed for exact-session continuation, not for browsing across projects.

After I crossed four active repos, I built a small desktop workspace that groups Claude Code and Codex sessions by project. It reads the same local JSONL files — no cloud, no API keys — and presents them in a browsable project view. I use it to find the right session before I /resume.

https://github.com/Harukaon/shelf

It is not a replacement for /continue, /resume, or CLAUDE.md. It sits beside them as a retrieval layer.

Bottom line

Claude Code is already powerful. The marginal gain from naming sessions, maintaining a correction log, and knowing which command to use when is larger than the gain from most configuration tweaks. And when project count grows, having a way to browse old sessions before resuming them pays for itself quickly.

Claude Code memory, resume, and session retrieval are three different jobs

Echo — Tue, 02 Jun 2026 05:27:25 +0000

I used to think Claude Code's memory, /resume, and session history were all solving the same problem. They are not. Once I separated them, my workflow got a lot less fragile.

1. Memory is for reusable facts

CLAUDE.md, .claude/rules/, and auto memory are for information that should carry into future sessions. This is where project conventions, build commands, debugging notes, and repeated corrections belong.

Good use cases:

"Always use pnpm in this repo."
"The integration tests need Redis."
"API handlers live under this directory."
"Claude keeps missing this convention, so write it down."

This is not the same as reopening an old conversation. It is a way to give the next conversation better starting context.

2. Resume is for a known session

claude --continue reopens the most recent conversation in the current directory.

claude --resume reopens a specific session by ID or name, or lets you choose from a picker.

This is the right layer when you know which conversation you want to continue. Naming sessions helps a lot here.

Good use cases:

You stopped working on a PR yesterday and want to continue it.
You named the session auth-refactor and want to reopen it.
You only need the most recent conversation in this repo.

3. Retrieval is for when you forgot which session it was

The harder case is not "can Claude continue a known session?"

The harder case is "which old session was that?"

After a few repos, the ID, date, terminal tab, and exact session name blur together. You may remember the project, bug, or decision, but not the session handle. Digging through ~/.claude/projects/ raw JSONL files is not a workflow.

That is a separate retrieval problem:

browse old sessions by project
find the relevant conversation before reopening it
avoid guessing session IDs or scrolling through a flat picker
keep Claude Code and Codex work visible across repos

This is the layer I built Shelf for: https://github.com/Harukaon/shelf

Shelf is not a replacement for --continue, --resume, CLAUDE.md, or auto memory. Those native layers are useful. Shelf is meant to sit beside them as a desktop workspace for browsing and reopening Claude Code and Codex sessions by project.

Short version

Memory is for reusable facts.
Resume is for a known session.
Retrieval is for finding the old session when you do not remember the ID, name, tab, or date.

I keep the three layers separate now and it stopped most of the "where did that conversation go?" panic.

Treat AI coding sessions as project infrastructure

Echo — Mon, 01 Jun 2026 22:36:35 +0000

Most AI coding workflows treat the current session as the important part.

That makes sense while you are in the loop. You ask Claude Code to inspect a tricky bug, or you queue Codex to write a PR, and the useful context is right there in front of you.

The problem starts a week later.

You remember that one session found the exact migration edge case. You remember another one explained why the quick fix was wrong. You might even remember the project. But you do not remember the session ID, the terminal tab, or the exact prompt that got you there.

That is the point where AI coding sessions stop being conversations and start becoming project infrastructure.

Here is the split that has worked best for me.

1. Keep durable rules in project files

Files like AGENTS.md, CLAUDE.md, or .codex/rules are good for behavior that should apply every run:

coding style
test expectations
release rules
known architecture constraints
commands that should or should not be used

This is not session history. It is the baseline contract for the project.

If you correct the agent twice on the same pattern, that correction probably belongs in one of these files.

2. Keep active work in a handoff document

For a feature or refactor, I like having a short implementation.md or handoff.md.

It should answer a few boring questions:

what are we changing?
what phase are we in?
what did the last agent already try?
what still needs human review?
what tests were run?

This works especially well when Claude Code and Codex are both touching the same repo. Claude Code can help explore and make decisions locally, while Codex can take a narrower task and return a PR. The handoff document keeps those runs from drifting apart.

3. Treat old sessions as searchable project records

The raw transcripts usually exist somewhere. For Claude Code, that often means digging through local session files. For Codex, the useful context may be split across tasks, PR notes, and local terminal work.

The hard part is not that the data is gone.

The hard part is finding the right old conversation when you only remember the project and the decision.

That is why I ended up building Shelf: a small open-source desktop app for browsing Claude Code and Codex sessions by project.

Repo: https://github.com/Harukaon/shelf

The goal is simple: old AI coding sessions should be reopenable without remembering opaque session IDs or spelunking through terminal history.

It is built with Tauri v2, Rust, TypeScript, Vite, and xterm.js, and currently targets macOS Apple Silicon and Linux.

My current rule of thumb

If it affects every future run, put it in project rules.

If it affects the current feature, put it in a handoff doc.

If it explains why a past decision happened, make sure the old session is easy to find again.

That third bucket is easy to ignore until you have twenty sessions across the same project. After that, retrieval becomes part of the workflow.

AI coding sessions are not just chat logs. They are project history.

A practical way to keep AI coding sessions from becoming disposable

Echo — Mon, 01 Jun 2026 19:13:08 +0000

AI coding tools make it easy to generate code, but they also create a quiet documentation problem: useful reasoning gets trapped inside sessions that are hard to find later.

The most useful parts of an AI session are often not the final patch. They are the dead ends, assumptions, trade-offs, and test ideas that led to the patch.

A few practices that help:

Start sessions from the correct project folder.
Name work around the task, not the model: auth-timeout-fix, migration-plan, release-checklist.
Keep important prompts and decisions close to the repo.
Review old sessions before asking the model to solve a similar bug again.
Treat session recovery as part of your dev environment, like restoring editor tabs.

I have been building this workflow into an open-source desktop app called Shelf.

Shelf is not another coding model. It is a small Tauri desktop workspace manager for people who use Claude Code and Codex across multiple repos.

The current version can:

organize sessions by project
resume previous Claude Code and Codex sessions
scan local AI conversation history
restore workspace state after restart
keep file tree + real PTY terminal in the same window

The main idea is simple: AI coding history should be browsable, not disposable.

Repo: https://github.com/Harukaon/shelf

Related: I also wrote a short workflow note on organizing Claude Code and Codex sessions across projects: https://dev.to/uzoma_uche_3ec83974b4a8a5/organizing-claude-code-and-codex-sessions-across-projects-722

DEV Community: Echo

Why I built a small desktop app to stop losing my Claude Code sessions

Found a tool that finally organizes my Claude Code chaos

Three Small CLI Tools I Built to Make Claude Code Feel Less Like a Black Box

Three Small CLI Tools I Built to Make Claude Code Feel Less Like a Black Box

1. cc-tail — stream the last N tool calls

2. cc-cost — session cost by project

3. cc-where — where did the model touch the file system?

What these tools do not do

Three PreToolUse Hooks I Stopped Using (and What Replaced Them)

Three PreToolUse Hooks I Stopped Using (and What Replaced Them)

1. "Don't edit files outside the project" hooks

2. "Strip secrets from tool output" hooks

3. "Inject project context on every Read" hooks

What I still use

Why I Keep a Per-Project Investigation Log Outside Claude Code

Why I Keep a Per-Project Investigation Log Outside Claude Code

Subagents vs Hooks in Claude Code: Picking the Right Tool for the Right Job

Subagents vs Hooks in Claude Code: Picking the Right Tool for the Right Job

CLAUDE.md as a Forcing Function: How Writing a Project Constitution Cleans Up Your Tooling

CLAUDE.md as a Forcing Function: How Writing a Project Constitution Cleans Up Your Tooling

From Terminal Tabs to Project Workspaces: How I Organize Claude Code and Codex Sessions

From Terminal Tabs to Project Workspaces: How I Organize Claude Code and Codex Sessions

What I actually needed

What I built

Architecture notes (for the curious)

The habit change

Five Claude Code habits that cost nothing and save hours

1. Name your sessions immediately

2. Treat CLAUDE.md as a correction log, not a spec

3. Know the difference between /continue and /resume

4. Export decisions before they disappear

5. Separate memory from retrieval

Bottom line

Claude Code memory, resume, and session retrieval are three different jobs

1. Memory is for reusable facts

2. Resume is for a known session

3. Retrieval is for when you forgot which session it was

Short version

Treat AI coding sessions as project infrastructure

1. Keep durable rules in project files

2. Keep active work in a handoff document

3. Treat old sessions as searchable project records

My current rule of thumb

A practical way to keep AI coding sessions from becoming disposable

1. `cc-tail` — stream the last N tool calls

2. `cc-cost` — session cost by project

3. `cc-where` — where did the model touch the file system?