TL;DR

TL;DR: I configured Claude Code and Codex CLI to act as my personal knowledge management system. Using CLAUDE.md files, custom slash commands, and agents, I automate note-taking during tasks and curate a searchable knowledge base visualized with Obsidian.

Key benefits:

  • Context persistence across AI sessions
  • Task notes automatically capture what matters
  • Knowledge base grows organically from your work
  • Works with both Claude Code and Codex CLI (with some work-arounds) via shared config

Get the code: Claude Code knowledge repo

Prerequisites:
  • Claude Code v2.0.5 or Codex CLI v0.42.0
  • Obsidian v1.9.14
  • Folder locations: $HOME/.claude, $HOME/.codex

Tested with: Claude Code v2.0.5 · Codex CLI v0.42.0 · Obsidian v1.9.14 · OS: Linux (as of 2025-10-06)

Intro

A couple months ago I saw McKay Wrigley talking about how he was using Claude Code to write notes and build a knowledge base that can be navigated via Obsidian.

The idea sounded good to me, so I thought "why don't I try the same?". After building it and using it for a couple months, I have to say I'm happy about it and the approach has helped me quite a bit.

In this article I'll explain how I configured my setup and how I refactored it to be compatible with both Claude Code and Codex CLI.

At the end of the article, you can see the link to the public GitHub repo in which I keep my CLAUDE.md, AGENTS.md and other relevant files.

CLAUDE.md, slash commands, and agents

CLAUDE.md hierarchy

Claude Code can be customized via CLAUDE.md files. These are "memory"/instructions files that Claude automatically loads. In Linux, the main one is stored under /etc/claude-code/CLAUDE.md and can be extended/overridden by project files in the current repo (e.g., ./CLAUDE.md or ./.claude/CLAUDE.md) and/or by a user file in your home folder ($HOME/.claude/CLAUDE.md).

Basically, Claude Code loads the CLAUDE.md files in a hierarchical structure:

  1. Enterprise policy in /etc/claude-code/CLAUDE.md (for Linux users, if present);
  2. Project memory in ./CLAUDE.md or ./.claude/CLAUDE.md;
  3. User memory in $HOME/.claude/CLAUDE.md.

Important note: CLAUDE.md guides behavior. Actual configuration (e.g., MCP servers, permissions) lives in settings.json files (with a similar - but not the same - hierarchical structure).

Custom slash commands

Claude Code offers a couple of slash commands by default (e.g., /context, /config, /memory) and also allows users to define custom slash commands.

The custom slash commands are nothing more than prompts, which means you should use them to define frequently-used prompts.

For example, if you often ask Claude Code to review your git diff taking into consideration security aspects, naming standards, etc., instead of writing that long prompt every time you can just save it in $HOME/.claude/commands/git_diff_review.md (or, if you want the prompt specific per project, save the file under ./.claude/commands/) and then call it by using /git_diff_review inside Claude Code.

You can also pass arguments to the command (e.g., /git_diff_review only staged files) and reference them with $ARGUMENTS.

If in your git_diff_review.md you have something like

Do a git diff and follow the instructions $ARGUMENTS [...]

It becomes

Do a git diff and follow the instructions only staged files [...]

Namespacing and folders

You can also organize your custom slash commands per folder. This helps in case you have multiple slash commands with the same name (e.g., the default /context and a custom /user:context) or if you want to have different slash commands per context (e.g., /git:review for code reviews and /docs:review for review on documentation).

Taking into consideration these examples, the folder structure would be (assuming we are only using commands in the home folder):

$ tree commands/
commands/
├── docs
│   └── review.md
├── git
│   └── review.md
├── my_awesome_command.md
└── user
    └── context.md

As you'll see later, I use the user:context slash command: it's stored in a user folder and it's done like this to avoid conflicts with the default /context slash command:

Claude Code showing /context and /user:context slash commands.

Customizing agents

Note: even though the docs call them "subagents", in this post we are referring them as agents because the command to create them is /agents.

According to Claude Code official documentation, "Subagents are pre-configured AI personalities that Claude Code can delegate tasks to.".

Each agent has its own specification (as in, custom system prompt), purpose, allowed tools it can use (if necessary) and, very important, its own context window.

Agents can be defined as Markdown files in .claude/agents/ folder (similar to before, the order is your current project -> your home folder).

You can create/edit an agent by calling /agents or manually edit the file if necessary. The agents file format can be found here.

Once the agent is created, you can tell Claude Code to use it. Sometimes, Claude Code also proactively calls the agent (based on the agent description and current task context).

For best practices, please read the official documentation.

Notes writer and knowledge curator

When we work in a task, we get knowledge on the topic: how tool xyz works, how the architecture of our project is designed, the details on why we had to configure something that way, etc.

While I was working on tasks with Claude Code, I realized we can take advantage of all the context in the Claude Code conversation and write down all the knowledge we acquired while doing the task.

So I decided to configure Claude Code to take notes on the tasks we are doing and also to write down more advanced knowledge base documents.

Task notes

Having Claude Code taking notes on the tasks we are working on works great for me due to multiple reasons:

  • it helps me keep track of the task progress (what's done, what's ongoing, what needs to be done);
  • it records important information about the task (for example, we need to provision this pod with 512 MiB requested memory because it has spikes during cronjob runs);
  • and, my favourite feature, it's a great way to give context to Claude Code!

I think it's important to expand more on the last point above: by "giving context" to Claude Code I mean we can start a Claude Code with the correct task context. We just need to tell it to search in its notes for the topic we want to work on, and then Claude Code "loads" already with the correct information.

An important detail on how I configured the task notes: I don't care what Claude Code writes there. This is on purpose, to mimic how I would work with a human: it's their notes, I don't review them.

This is explicitly stated in CLAUDE.md:

- Task notes are for Claude's use only

/user:context command

Here's an example (a real one, from a couple days ago when I was exploring Ollama) in which I tell Claude Code to take notes and then load the notes information at the beginning of the conversation:

  1. I'm working on a new topic (in this case, Ollama) and at some point I notice that there is new information (for me) that is important to write down. I ask Claude Code to write down the notes

    Creating a new task note; Claude writes notes.md under the topic folder.

  2. When I start Claude Code, I can use a slash command (link to repo with slash command) that tells it which topics he should look for in the tasks: claude "/user:context ollama Modelfile"

  3. Then Claude Code starts and will look into its tasks/knowledge base for the topics (in this case, keywords are ollama and Modelfile) and, once it's finished, will have the correct information in context!

    /user:context loads matched notes and summarizes key points.

I know Claude Code has a /resume command to resume a conversation, but it's not the same as my /user:context: the default /resume only resumes conversations that happened in the same folder where we are launching Claude Code from; and it loads the entire thread, with all the messages and tokens: but sometimes I just want the summary (aka, the notes).

Knowledge base curator flow

The tasks notes flow works great, but sometimes I want a more robust documentation file on certain topics. For example, if we're working on redesigning architecture on a system, it's important to move the notes into a more robust documentation file.

When I get to that point, I use the review-knowledge slash command: it is configured with instructions on how to write down the knowledge base documents and it will call the knowledge-base-curator agent.

The agent will then process all the information and come up with a plan on what to write/modify in the knowledge base entry (or entries). Unlike the task notes, now I want to review what's written in these documents (the same way I would review documentation written by a human): so I configured the knowledge-base curator wait for me to accept the plan and only start writing the document afterwards.

Then I read the document (or the changes to an existing document), tell it if it should change something, and then Claude Code commits them.

Knowledge base curator proposes an enhancement plan based on task notes.

Obsidian integration

If you opened the claude-code-knowledge repository, you might have noticed that Obsidian is mentioned in the CLAUDE.md file and also in the knowledge base related files.

From Obsidian website:

Obsidian is a flexible and secure app that lets you store, link, and publish your notes on any device. You can shape Obsidian with plugins, themes, and open file formats, and create your own personal Wikipedia or digital garden.

I've used Obsidian on and off for the last few years and it can be a great tool to write/edit/read Markdown files.

One of its advantages is that it can use built-in tools to build very cool visualizations. For example, in plain Markdown we have an integration flow like

graph TD
    A[Command Execution] --> B[Scope Detection]
    B --> C[Content Analysis] 
    C --> D[Plan Generation]
    D --> E[User Approval]
    E --> F[Agent Deployment]
    F --> G[Specialized Execution]
    G --> H[Results Summary]

Which Obsidian (with the help of mermaid) will transform into a visual flow!

Obsidian rendering Mermaid diagram showing workflow from Command Execution to Results Summary.

And as the Knowledge base grows, you can take advantage of the Obsidian graph to see how the different documents are connected with each other:

Obsidian graph view showing interconnected knowledge base entries with nodes and links.

In this graph, some nodes point to a document that actually exists and others point to nothing because there are no documents connected to that node. This is a feature, not a bug: it's to show to the user how different documents connect. If we click on the nodes that have no documents, a blank document will be created and we can start writing there.

To ensure that all these relations are properly setup, I explicitly tell the knowledge-base curator agent to take the links into consideration. And I do the same in the review knowledge slash command.

With this setup, we have Claude Code taking notes that are already prepared to be open in Obsidian, taking advantage of its great features.

Codex CLI bridge

Besides Claude Code, from time to time I also use Codex CLI. However, I felt that my experience with Codex CLI was worse because I didn't have my notes/knowledge curator flow.

So I decided to try using the exact same configurations for Codex CLI: moved the CLAUDE.md file and the folders agents and commands away from my $HOME/.claude folder and into a new folder in my system.

Then, in both Claude Code and Codex CLI I created symlinks to that new folder:

$ ls -lgo $HOME/.claude
total 3168
lrwxrwxrwx  1      34 16. Sep 16:08 agents -> $HOME/Documents/ai/agents
lrwxrwxrwx  1      37 16. Sep 16:47 CLAUDE.md -> $HOME/Documents/ai/CLAUDE.md
lrwxrwxrwx  1      37 16. Sep 16:45 commands -> $HOME/Documents/ai/commands/

$ ls -lgo $HOME/.codex/AGENTS.md
lrwxrwxrwx 1 37 16. Sep 16:47 $HOME/.codex/AGENTS.md -> $HOME/Documents/ai/CLAUDE.md

By doing this, I have both Claude Code and Codex CLI reading from the same instructions file. This avoids duplicated files and keeps everything more tidied up.

This works great for Claude Code (as it should, the files are the same, just located in another path), however it's not 100% compatible with Codex CLI: while Codex has built-in slash commands (like /model), it lacks official support for custom slash commands and subagents.

I haven't found a way to make the agents work, but for the slash commands topic I found a workaround: given that the slash commands are just extra prompts injected into the conversation, I figured that we can replace them by injecting the prompt via bash script.

For example, in order to load the context (basically the /user:context slash command mentioned earlier) I just need to call a custom codex-context function with the context topics:

Codex CLI helper loads context and summarizes with actionable bullets.

This approach doesn't work great yet, so the bash script helper is only published as a WIP.

Another issue that I haven't been able to solve was that, unlike Claude Code, Codex CLI always searches for context when I send it a new prompt. Sometimes I don't want it to search context, I'm just using it for simple tasks. This is a bit annoying, but haven't had the time to look deeply into it.

Limitations

  • No subagents: Codex CLI can’t invoke custom agents; only shared instructions in CLAUDE.md are reused.
  • No custom slash commands: Codex has some built-ins (e.g., /model) but doesn’t support user-defined commands.
  • Context search behavior: Codex currently searches context on each new prompt; there’s no toggle to skip it.
  • Parity gaps: The symlinked config unifies prompts, not capabilities—expect different tool behavior between apps.
  • Helper script is WIP: The bash workaround emulates commands but is brittle and may change.

Conclusion

Having Claude Code acting as my personal notes writer is being very helpful to my workflow: saves me a lot of time and it also helps me get back into tasks when I'm multitasking (which is the life of a DevOps engineer, always handling multiple tasks at the same time).

The knowledge base feature also has great potential, but I haven't had the chance to test it extensively in ever-growing systems. However, I see this as something that Claude Code (or any other AI CLI tool) can do. If not now, soon.

I believe that by configuring our AI tools to keep information in text files we can extract valuable help in a format that we really understand well: the text format.