DEV Community: Nishikanta Ray

What If Your Coding Agent Could Remember What It Learned Yesterday?

Nishikanta Ray — Thu, 17 Sep 2026 16:28:47 +0000

I built Attic to help Claude Code and Codex CLI remember what they discover — and now you can save knowledge from your browser too.

You ask your AI coding assistant to investigate a bug.

It searches the repository. Reads five files. Follows a few imports. Runs some commands. Finally, it tells you:

"Found it. The authentication check happens after the desktop sub-window is created."

Great. You fix the bug.

A few days later, you start a new session.

You ask the assistant to investigate another issue in the same area.

It searches the same files.

Reads the same imports.

Runs the same commands.

And eventually discovers the same thing you already knew.

You just paid for the same investigation twice.

Maybe three times.

This is the problem I wanted to solve with Attic — an open-source knowledge persistence tool for AI coding assistants.

But the interesting part isn't simply saving notes.

It's the design behind making those notes useful across sessions, after context compaction, and now even from your browser.

GitHub: https://github.com/NishikantaRay/Attic

The problem: Your AI knows more than your codebase

Let's start with a simple example.

Imagine you're working on a JavaScript monorepo.

You ask Claude Code:

"Why is the cloud package failing to load?"

The assistant investigates and finds:

// packages/cloud/index.js

export default cloudClient;

export default cloudConfig;

Two default exports.

The file throws a syntax error.

The assistant explains the issue. You fix it.

But where does that knowledge go?

If you only keep the conversation, the discovery is trapped inside that session.

If you start a new session, your assistant may have to rediscover the same problem.

The codebase contains the bug fix, but it doesn't necessarily contain the reasoning that helped you find it.

And reasoning is often what you need the next time.

Another example: Documentation versus reality

Suppose your project has a rule:

"All desktop sub-windows must wait for authentication before rendering."

But the actual implementation creates the window before the authentication gate finishes.

Your assistant investigates and discovers the contradiction.

That's valuable knowledge.

Not just:

There is a bug.

But:

The desktop sub-window can be created before the authentication gate
completes, despite the documented requirement.

That tells the next investigation where to look.

It also tells a teammate what assumption is unsafe.

It explains why the code behaves the way it does.

This kind of knowledge is easy to lose.

And it isn't limited to bugs.

It includes:

Architectural decisions.
Repository conventions.
Failed approaches.
Important file locations.
Authentication assumptions.
Performance discoveries.
Why a particular implementation exists.
Things you should never repeat.

Your codebase is a library of implementation.

Your AI assistant's discoveries are the notes in the margins.

The question is: Where do those notes live?

Meet Attic: A memory shelf for your coding agent

Attic is an open-source tool designed to help AI coding assistants persist and reuse knowledge.

It works with:

Claude Code.
Codex CLI.

The idea is straightforward:

Write what you learn to a file. Keep a small index in context. Retrieve the details when you need them.

No need to put every discovery into the assistant's context forever.

No need to rebuild the same understanding from scratch every session.

And no need to turn your entire repository into a giant collection of instructions.

Attic gives the agent a place to store useful discoveries.

Think of it as a small knowledge library inside your project.

The library analogy that makes Attic click

Imagine you have a library.

You have 200 books.

You don't carry all 200 books around with you.

You carry a catalogue.

The catalogue tells you:

Which books exist.
Where they are.
Which ones are important.
What each book is about.

When you need a particular book, you look it up.

Attic follows the same idea.

The `.attic/` folder is the library

A typical Attic knowledge folder contains Markdown files:

.attic/
├── INDEX.md
├── DECISIONS.md
└── items/
    ├── f1.md
    ├── f2.md
    ├── f3.md
    └── ...

The exact files and commands depend on the installed version, but the core concept is consistent:

The knowledge lives on disk. The index helps the agent find it.

`INDEX.md` is the catalogue card

The index is not supposed to contain every detail.

It's a compact representation of what matters.

For example:

# Attic Index

## Pinned

- f3: Authentication must complete before
  desktop sub-windows are created.

## Recent findings

- f12: Cloud package has duplicate default exports.
- f11: API client is initialized in the shared module.
- f10: The docs and implementation disagree
  about the authentication lifecycle.

## Older items

95 older items not shown.
Use /attic-recall <topic>.

This is an illustrative example of the idea, not a claim about the exact generated format.

The agent can see the important information without loading the entire knowledge base into every prompt.

When more detail is needed, it can recall the relevant item.

That's the distinction:

The index is the catalogue. The Markdown files are the books.

Why not just put everything in the system prompt?

This is a reasonable question.

If the assistant needs the information, why not inject all of it?

Because context is limited.

And even when you have enough context, more context isn't automatically better.

Imagine an assistant working on a project with 200 findings.

If every finding is included in every session, the prompt becomes filled with:

Old discoveries.
Superseded decisions.
Unrelated bugs.
Details from previous tasks.
Information that may not matter to the current question.

The agent now has to spend attention deciding what matters.

Attic takes a different approach.

Keep the index small

Attic's runtime includes logic for loading the index and keeping its injected representation compact.

The repository's design notes describe an index that prioritizes pinned findings, recent items, and compact summaries for older knowledge.

The important idea is not a magic token number.

It's this:

Don't force the assistant to carry the entire library when a catalogue will do.

Retrieve the details when needed

Suppose the agent is investigating authentication.

It doesn't need to read every database discovery, UI decision, and deployment note.

It needs the authentication-related knowledge.

That's where recall becomes useful.

The four commands: Put knowledge in, get knowledge out

Attic's commands are organized around a simple workflow.

1. `stash` — save what you learned

After an investigation, save the discovery.

Example:

/attic-stash

The exact command options depend on the installed version.

Conceptually, you are turning an ephemeral chat discovery into a persistent Markdown item.

Instead of:

"I think the auth gate is somewhere in the desktop code."

You save:

# Authentication gate and desktop sub-windows

The desktop sub-window creation path can run
before the authentication gate completes.

When investigating window lifecycle bugs,
check the auth gate before the window creation path.

Tags:
- authentication
- desktop
- lifecycle

Now that discovery has a home.

2. `recall` — find what you already know

Later, you can ask Attic to retrieve relevant knowledge.

Example:

/attic-recall authentication

The assistant can use the stored findings instead of starting from zero.

This is particularly useful when:

A new session starts.
You run /compact.
A teammate clones the project.
You return to an old feature.
You forgot why a particular design exists.

3. `index` — inspect the catalogue

The index helps you understand what the agent can see.

Example:

/attic-index

The idea is to inspect the compact catalogue rather than opening every item.

4. `pin`, `prune`, and `archive` — manage the shelf

Not every discovery deserves permanent prominence.

Some knowledge is important forever.

Some is useful for a week.

Some becomes obsolete after a refactor.

Attic provides commands for managing that lifecycle:

/attic-pin
/attic-prune
/attic-archive

The exact syntax depends on the version and installed commands.

The important design decision is that knowledge needs management.

A memory system that only writes and never cleans up eventually becomes another source of noise.

The part I find most interesting: The index is not the memory

This is the design detail worth understanding.

A common approach to agent memory is:

Store a large amount of information and inject it into the next prompt.

Attic separates storage from injection.

Storage

The detailed findings live in Markdown files.

They can contain context, explanations, file references, and reasoning.

Injection

The assistant receives a compact index.

The index tells it what exists and how to find it.

This separation gives you a useful property:

You can have a large knowledge base without making every prompt equally large.

For example:

Knowledge on disk:

200 findings
│
├── Pinned findings
├── Recent findings
└── Older findings
    └── Available through recall

The assistant doesn't need all 200 findings in context.

It needs enough information to navigate the collection.

This is a familiar pattern in software engineering:

Database versus index.
Filesystem versus directory listing.
Library versus catalogue.
Search engine versus document store.

Attic applies that idea to coding-agent memory.

What happens when you use `/compact`?

This is one of the reasons persistent memory matters.

Imagine a long coding session.

At the beginning, you ask:

"Understand the authentication flow."

The agent investigates.

It discovers:

The auth gate lives in one module.
The desktop window is created in another.
The window creation can happen before auth finishes.
The documentation assumes the opposite order.

You fix the problem.

Then the conversation becomes huge.

You use:

/compact

The context is reduced.

The agent may no longer have every detail from the earlier investigation.

If the key discovery existed only in the conversation, it can be difficult to recover.

But if you saved it to Attic:

.attic/items/f3.md

The knowledge remains on disk.

A later session can recall it.

The discovery has survived the conversation.

This is the central promise of persistent agent memory:

Your knowledge should outlive the context window.

The browser extension: Knowledge doesn't only happen in your terminal

Now let's talk about the feature that makes Attic particularly interesting.

Most coding-agent memory tools focus on what happens inside the terminal.

But developers learn things everywhere.

You might discover a useful fact while reading:

A GitHub issue.
A pull request.
A Stack Overflow answer.
A technical blog.
A framework documentation page.
A browser tab containing an important explanation.
A discussion about a design decision.

You might think:

"This is useful. I should save it."

Then you close the tab.

Or forget.

Or leave it in your browser history.

The information never makes it into your project's knowledge base.

Attic's browser companion is designed to close that gap.

Instead of only remembering what the coding agent discovers, you can save useful knowledge from the browser into the same Attic shelf.

That is a powerful extension of the original idea.

Browser to project memory

Let's say you're investigating a bug in a Node.js application.

You open a GitHub issue discussing a subtle behavior in a dependency.

The issue contains the explanation you need.

You don't want to copy the entire page into your project.

You want to save the useful discovery.

The workflow becomes:

Read useful information in browser
          │
          ▼
       Clip it
          │
          ▼
  Save to Attic knowledge
          │
          ▼
  Recall it in a future session

The browser becomes another input into your project memory.

This is important because developers don't learn only by asking an AI agent questions.

They learn by reading.

And a lot of that reading happens outside the terminal.

What is a clip?

A clip is a way to capture useful browser content and save it as a knowledge item.

Imagine reading this on a documentation page:

"The authentication callback must complete before the desktop window is created."

Instead of copying the entire article into a notes app, you can clip the useful content into Attic.

The saved item might look like:

# Authentication callback lifecycle

Source: Browser research

The authentication callback must complete
before the desktop window is created.

This matters because creating the window
too early can bypass the expected auth gate.

Tags:
- authentication
- desktop
- lifecycle

Now your browser research becomes part of the same knowledge collection used by your coding agent.

The exact clip UI and available options depend on the installed extension version.

Why reuse the CLI writer instead of building a second memory system?

This is one of the most important design calls in Attic's browser companion.

A tempting approach would be to build a separate browser storage system.

Something like:

Browser extension
       │
       ▼
Browser database
       │
       ▼
Browser-only notes

Then the CLI would have its own memory system:

CLI
 │
 ▼
.attic/
 │
 ▼
CLI-only notes

Now you have two systems.

Two storage formats.

Two sets of rules.

Two places to search.

Two systems to maintain.

Attic takes a different approach.

The browser companion reuses the CLI writer.

The repository's design notes explicitly call out that the companion uses the existing CLI writer rather than reimplementing it.

Conceptually:

                 ┌────────────────────┐
                 │  Browser extension │
                 └─────────┬──────────┘
                           │
                           ▼
                 ┌────────────────────┐
                 │   CLI writer       │
                 └─────────┬──────────┘
                           │
                           ▼
                      .attic/
                           │
                 ┌─────────┴──────────┐
                 ▼                    ▼
             INDEX.md             items/*.md

This is a classic software engineering principle:

Reuse the existing source of truth instead of creating a second implementation.

The CLI already knows how to write Attic items.

The browser companion should not need to invent a different way to do the same job.

That keeps the storage model consistent.

It also means the knowledge saved from your browser can be used by the CLI.

And knowledge saved from the CLI can be found in the same collection.

One shelf.

Multiple ways to put books on it.

The subtle distinction: Edit is not stash

This is another design decision worth talking about.

At first glance, these two actions might seem similar.

Stash

You discover something new.

You want to add it to the knowledge base.

New discovery → Add a knowledge item

Edit

You already have a knowledge item.

You want to correct or update it.

Existing item → Replace its content

These are not the same operation.

Suppose you have this finding:

# Authentication lifecycle

The desktop window is created before
the authentication callback completes.

Later, you investigate more deeply and discover that the bug has been fixed.

You edit the existing item:

# Authentication lifecycle

The desktop window now waits for the
authentication callback to complete.

The previous behavior was caused by
the window creation path running too early.

You have updated the knowledge.

You haven't discovered a second, unrelated fact.

Why appending everything is a problem

If editing simply appended another copy, you could end up with:

# Authentication lifecycle

The desktop window is created before auth.

---

# Authentication lifecycle

The desktop window waits for auth.

---

# Authentication lifecycle

The previous behavior was caused by...

Now the agent has to reconcile multiple versions.

That's noise.

The repository's design notes explicitly distinguish editing from stashing:

Editing replaces; stashing appends.

This is a small detail, but it reflects a larger principle:

Memory needs both creation and correction.

A knowledge system that only adds information eventually becomes cluttered with stale information.

Why there is no delete endpoint

This might sound strange.

If a knowledge item is wrong, why not just delete it?

The design notes for Attic's browser companion call out that there is no delete endpoint.

Instead, the system provides management operations such as archive and prune.

There is a reason to be careful here.

Deleting knowledge can be destructive.

Imagine an agent saves an important architectural decision.

A browser clip accidentally overwrites it.

Or a user removes an item because it looks old.

The information may be gone before anyone realizes it was useful.

A safer approach is to separate:

Editing an existing item.
Archiving an item.
Pruning stale knowledge.
Permanently removing data, if supported through an intentional local workflow.

This is a design choice, not a universal rule.

Different tools may reasonably choose different deletion models.

But the principle is worth considering:

Memory should be managed deliberately, not casually destroyed.

The browser companion is also a security boundary

The moment a browser extension can write to your project files, security becomes important.

A browser extension is not the same as a trusted terminal command.

It runs in a different environment.

It may interact with content from arbitrary websites.

It needs a way to communicate with the local Attic server.

That means the design has to answer:

Which origins can connect?
Which requests are allowed?
How is the local service authenticated?
Where can it write?
What happens when a user clips sensitive information?
Can arbitrary websites cause files to be written?

Attic's design notes identify several of these concerns:

Loopback communication.
A token.
A root allowlist.
Origin checks.
A credential scan for clips.

These are important because a browser-to-local-file bridge should not behave like an unrestricted file-writing API.

Loopback: Keep communication local

The companion communicates with a local server.

The goal is to keep the interaction on the developer's machine rather than sending knowledge to a remote cloud service.

The repository's design notes identify loopback communication as part of the implementation.

This is aligned with the project's broader local-first approach.

The knowledge is intended to live in the project's .attic/ directory.

Token authentication

A local service still needs protection.

Just because something runs on localhost doesn't mean every request should be trusted.

Attic's browser server uses a token as part of its request validation.

Conceptually:

Browser extension
       │
       │ request + token
       ▼
Local Attic server
       │
       ▼
Validate request
       │
       ▼
Write knowledge item

The exact request format is an implementation detail.

The important point is that the server isn't designed as an unauthenticated arbitrary file-writing endpoint.

Root allowlist: Where can it write?

This is another useful security concept.

Suppose the browser companion could tell the server:

Write this content to:

/Users/me/anything/on/my/computer

That would be dangerous.

A project memory tool should not be allowed to write to arbitrary locations.

Attic's design notes identify a root allowlist in the server.

The intended principle is:

Restrict file writes to approved project roots.

That limits the scope of what the companion can modify.

Credential scanning: Don't stash secrets

This is particularly important for browser clipping.

Imagine you are reading a page containing:

API_KEY=super-secret-value

You click "Clip."

Should that secret be saved to your project's memory?

No.

Attic's design notes identify a credential scan that refuses a clip containing a credential.

This is a practical safeguard.

But it doesn't mean every secret will be detected.

You should still avoid clipping:

API keys.
Passwords.
Session tokens.
Private access tokens.
Credentials.
Personal secrets.

A browser extension that can save content needs to treat sensitive information as a first-class concern.

The local-first philosophy

One of the things I like about Attic is that its design stays close to ordinary developer tools.

The knowledge is stored as Markdown.

The project can inspect it.

The files can be version-controlled.

And the runtime is designed around local filesystem operations rather than a cloud memory service.

The repository describes the runtime as using Node.js fs and path, with no network calls in the plugin runtime.

That gives the project a straightforward mental model:

Your project
    │
    ├── Source code
    ├── Documentation
    ├── Tests
    └── .attic/
         ├── INDEX.md
         ├── DECISIONS.md
         └── items/

Your agent's memory is another part of the repository.

Not a mysterious remote database.

Not a separate SaaS dashboard.

Not a service you need to query over the internet every time the agent needs to remember something.

But should you commit `.attic/` to Git?

This is an important practical question.

If the knowledge lives in your project, it can potentially be shared with the team.

For example:

Developer A
    │
    ▼
Saves an architectural discovery
    │
    ▼
Commits .attic/
    │
    ▼
Developer B pulls the changes
    │
    ▼
Agent can recall the discovery

The repository notes describe .attic/ as surviving a Git clone only if it is committed rather than ignored.

That distinction matters.

If you want shared project memory, you need to decide:

Should the knowledge be committed?
Should some findings remain local?
How should stale findings be managed?
How should conflicting changes be merged?
What information is appropriate for the whole team?

For a team project, knowledge management becomes part of the repository workflow.

A complete example: From bug investigation to reusable knowledge

Let's walk through a realistic workflow.

Step 1: Start a new investigation

You ask Claude Code:

"Investigate why the desktop sub-window sometimes appears before authentication."

The agent searches the codebase.

It discovers:

packages/desktop/window.js
packages/auth/gate.js
packages/desktop/bootstrap.js

It traces the execution path.

Step 2: The agent finds the root cause

The agent explains:

"The window creation call happens before the authentication callback completes."

You fix the issue.

Step 3: Save the discovery

You stash the important knowledge:

/attic-stash

The saved item contains something like:

# Desktop window authentication lifecycle

The desktop window creation path can run
before the authentication callback completes.

When investigating window lifecycle issues,
check the auth gate before window creation.

Relevant areas:
- packages/desktop/window.js
- packages/auth/gate.js
- packages/desktop/bootstrap.js

Tags:
- desktop
- authentication
- lifecycle

Step 4: Start a new session

A few days later:

"Why is the desktop window lifecycle failing?"

The agent can inspect the Attic index and recall relevant knowledge.

Instead of immediately rediscovering the entire execution path, it has a useful starting point.

Step 5: Update the knowledge after the fix

You discover a more precise explanation.

You edit the existing item.

Now the knowledge stays current.

This is the lifecycle that matters:

Investigate
    ↓
Discover
    ↓
Stash
    ↓
Recall
    ↓
Update
    ↓
Reuse

It's not magic.

It's a disciplined way to make discoveries persistent.

What Attic does not try to do

It's worth being clear about the scope.

Attic is not a replacement for:

Your source code.
Your Git history.
Your issue tracker.
Your documentation.
Your test suite.
Your own engineering judgment.

It's a knowledge persistence layer for coding-agent workflows.

It helps preserve discoveries and make them available again.

It doesn't guarantee that the assistant will always recall the right item.

It doesn't guarantee that every saved finding is correct.

It doesn't eliminate the need to verify facts.

And it doesn't mean the agent should blindly trust old notes.

A stale memory can be just as dangerous as no memory.

That's why editing, pruning, and archive workflows matter.

The bigger idea: Agents need a knowledge lifecycle

When people talk about AI coding assistants, they often focus on:

Better models.
Larger context windows.
Faster inference.
More tool calls.
Better code generation.

Those things matter.

But there is another problem:

What happens to the useful knowledge after the task ends?

A coding agent might discover:

The API client is initialized in a shared module.

That can be valuable.

But if it exists only in the chat, the next session may have to rediscover it.

The same is true for:

Why a dependency was chosen.
Why a workaround exists.
Why a particular file is important.
Which approach failed.
What assumption caused a bug.
What the team should avoid repeating.

These are not necessarily code changes.

They are discoveries about the codebase.

And they deserve a place to live.

Why browser memory is a natural next step

The browser extension expands the idea beyond terminal-based discovery.

Developers constantly learn from external information.

They read a blog post.

Find a GitHub issue.

Understand a framework quirk.

Discover a workaround.

Read a discussion about a bug.

That knowledge is useful even if the AI agent didn't discover it itself.

The browser companion makes it possible to capture useful information and bring it into the same local knowledge system.

This creates a broader workflow:

             ┌───────────────┐
             │   Terminal    │
             │ Claude/Codex  │
             └───────┬───────┘
                     │
                     ▼
              ┌────────────┐
              │   Attic    │
              │  Knowledge │
              └────────────┘
                     ▲
                     │
             ┌───────┴───────┐
             │               │
      ┌──────┴──────┐ ┌──────┴──────┐
      │ CLI stash   │ │ Browser     │
      │             │ │ clip        │
      └─────────────┘ └─────────────┘

One knowledge shelf.

Different ways to add information.

The same place to recall it.

Getting started

You can explore Attic here:

GitHub: https://github.com/NishikantaRay/Attic

The project is designed for Claude Code and Codex CLI.

A typical workflow is:

1. Install Attic
2. Initialize it in your project
3. Investigate a problem
4. Stash useful discoveries
5. Recall them in later sessions
6. Manage the knowledge as it evolves
7. Use the browser companion to capture useful research

For the exact installation and usage commands, follow the repository's current README and release documentation.

Final thoughts

I think the most interesting thing about AI coding assistants isn't just how much code they can write.

It's how much they can discover.

An agent can investigate a codebase for ten minutes and uncover something that would take a developer much longer to understand.

But if that discovery disappears when the session ends, you lose part of the value.

Attic is built around a simple idea:

Don't make your AI coding assistant rediscover what it already learned.

Write the discovery to a file.

Keep a compact index.

Recall the details when needed.

And now, when useful knowledge comes from your browser, clip it into the same shelf.

The future of AI coding assistants may not just be about giving agents more context.

It may also be about giving them better ways to remember.

Try Attic

If you use Claude Code or Codex CLI and you've ever thought:

"I know we already solved this. Why is the agent investigating it again?"

Attic is worth exploring.

GitHub: https://github.com/NishikantaRay/Attic

If you try it, I'd be interested to hear how you manage your agent's knowledge.

What would you want your coding assistant to remember permanently?

ai #claudecode #codex #opensource #developer-tools #codingagents #artificialintelligence #productivity

AI Skills Are Not Just Prompts: A Practical Architecture for Building, Evaluating, Shipping, and Maintaining Agent Skills

Nishikanta Ray — Thu, 03 Sep 2026 19:13:59 +0000

The current generation of AI coding agents makes it surprisingly easy to create a "skill."

Write a Markdown file. Add instructions. Give it a name. Put it inside .claude/skills/. Done.

Except it isn't.

As soon as you build more than a handful of skills, a different set of problems appears:

Which skill should activate?
Why did two skills activate at the same time?
Why did the agent ignore an important instruction?
What belongs in a skill versus a rule, agent, hook, or script?
How much context should the skill load?
How do you test whether the skill actually works?
What happens when the underlying framework changes?
How do you distribute skills?
How do you retire obsolete skills?
How do you prevent dozens of skills from becoming an unmaintainable mess?

At that point, AI skills stop looking like prompts and start looking like software systems.

A production-grade AI skill is not merely a Markdown prompt. It is a versioned, testable, routable, enforceable software component with a defined lifecycle.

1. The Skill Lifecycle

A useful way to understand an AI skill is to look at its entire lifecycle:

Runtime
   ↓
Scope / Fit
   ↓
Triggers
   ↓
Architecture
   ↓
Anatomy
   ↓
Content
   ↓
Enforcement
   ↓
Measurement
   ↓
Shipping
   ↓
Maintenance
   ↓
Portfolio

Each stage answers a different question:

Stage	Core question
Runtime	How does the skill load and execute?
Fit & scope	Should this be a skill at all?
Typing & triggers	When should it activate?
Architecture	How should the workflow operate?
Anatomy	What files make up the skill?
Content	How should instructions be written?
Enforcement	What can be enforced mechanically?
Measurement	How do we know it works?
Shipping	How do users receive it?
Maintenance	How does it survive change?
Portfolio	How do many skills coexist?

The important insight is that skill engineering covers the entire lifecycle, not just the writing of SKILL.md.

2. Chapter 00 — How Skills Load and Run

Before designing a skill, understand the runtime.

A skill may look simple on disk:

.claude/
└── skills/
    └── code-review/
        └── SKILL.md

But conceptually the runtime does something like:

User request
     ↓
Skill discovery
     ↓
Trigger evaluation
     ↓
Skill activation
     ↓
Instruction loading
     ↓
Reference/tool loading
     ↓
Agent execution
     ↓
Result

The important question is:

What does the agent actually see, and when does it see it?

This matters because context is limited.

A skill might contain:

SKILL.md
references/
    database.md
    security.md
    examples.md
    architecture.md
scripts/
    validate.js
    check.sh
templates/
    report.md

You usually don't want every file loaded for every request.

Instead:

Request
   ↓
SKILL.md
   ↓
Determine relevant task
   ↓
Load relevant reference
   ↓
Execute required script

This is progressive context loading.

The main skill file acts as an entry point rather than a giant knowledge dump.

Context Is a Resource

One of the biggest mistakes in AI skill design is treating context as free.

It isn't.

Design A — Everything in one file

SKILL.md
──────────────
3000 lines
50 examples
20 rules
10 workflows
15 edge cases

Design B — Layered knowledge

SKILL.md
   ↓
Routing
   ↓
references/
   ├── workflow.md
   ├── security.md
   └── examples.md

The second design gives you more control over what enters the model's context.

Design skills around context boundaries, not just file boundaries.

3. Chapter 01 — Fit and Scope

The next question is:

Should this behavior be implemented as a skill?

AI development environments often provide multiple primitives:

Skill
Rule
Agent
Hook
Script
Plugin

They are not interchangeable.

Skill

A skill describes how to perform a class of task.

Example:

database-migration

It might define:

1. Inspect schema
2. Inspect migration history
3. Design migration
4. Implement migration
5. Validate migration
6. Test rollback

Rule

A rule is a constraint:

Never modify production data directly.

That is policy, not a workflow.

Agent

An agent is useful when you need a distinct reasoning or execution role:

Main Agent
   ├── Research Agent
   ├── Security Agent
   └── Testing Agent

Hook

A hook responds to an event:

Before tool call
      ↓
Security check

or:

After file modification
      ↓
Formatter

Script

A script performs deterministic computation:

validate-schema.js

The AI may decide when to run it. The script determines how validation works.

4. The Boundary Is More Important Than the Skill

A good skill should explicitly state what it does not do.

For example:

This skill handles:

- PostgreSQL schema migrations
- Migration generation
- Migration validation
- Rollback testing

This skill does not handle:

- Application architecture
- Production deployment
- Database backups
- Infrastructure provisioning

Why?

Because skills tend to grow.

A developer starts with:

database migration

Then adds:

database design
query optimization
backup strategy
production deployment

Eventually the skill becomes:

database-engineering-everything

and becomes difficult to reason about.

Scope is a defense against skill inflation.

5. Chapter 02 — Typing and Triggers

Once you know what a skill does, you need to answer:

When should it activate?

Imagine:

frontend-review
backend-review
security-review
performance-review
database-review

The user says:

"Review my authentication API."

Multiple skills may be relevant.

You now have a routing problem:

                 User request
                      │
        ┌─────────────┼─────────────┐
        ↓             ↓             ↓
    Backend       Security       Performance

If everything activates, the system becomes noisy.

If nothing activates, the skill is useless.

Activation Is a Classification Problem

Think of activation as:

User request
      ↓
Intent classification
      ↓
Skill candidates
      ↓
Relevance evaluation
      ↓
Activation

Example:

Request	Expected skill
"Create a PostgreSQL migration"	Database migration
"Fix this React component"	Frontend
"Audit authentication"	Security
"Why is this query slow?"	Database performance
"Write a technical article"	Documentation

A good skill therefore needs a clear activation signature.

False Positives and False Negatives

False positive

"Write a blog about PostgreSQL"

→ security skill activates

False negative

"Why is my PostgreSQL migration failing?"

→ database migration skill does not activate

Both are important.

Therefore, evaluate activation separately from execution.

6. Chapter 03 — Shape and Architecture

Once a skill activates, what does it actually do?

There are several useful workflow shapes.

Route

A route chooses a path:

                 Request
                    ↓
                 classify
              /     |                   /      |                  Bug    Feature   Refactor
            ↓        ↓         ↓
         Debug    Implement  Refactor

Pipeline

A pipeline is sequential:

Research
   ↓
Analyze
   ↓
Plan
   ↓
Implement
   ↓
Test
   ↓
Review
   ↓
Report

This is particularly useful for engineering skills.

Loop

A loop supports iteration:

Implement
    ↓
Test
    ↓
Failed?
  /    Yes     No
 ↓       ↓
Fix    Complete
 ↓
Test again

For coding agents, this is natural:

Write implementation
        ↓
Run tests
        ↓
Read failure
        ↓
Modify implementation
        ↓
Run tests again

Failure becomes an expected workflow state rather than an exceptional event.

Map

A map splits a problem into independent pieces:

                 Research repository
                        │
          ┌─────────────┼─────────────┐
          ↓             ↓             ↓
       Frontend      Backend       Database
          ↓             ↓             ↓
       Findings      Findings      Findings
          └─────────────┼─────────────┘
                        ↓
                     Synthesis

Combining Shapes

Real skills often combine these patterns:

Route
  ↓
Pipeline
  ↓
Map
  ↓
Loop
  ↓
Final report

This is where AI skills start looking like workflow engines rather than prompts.

7. Chapter 04 — Anatomy

A mature skill might look like:

skills/
└── deep-research/
    │
    ├── SKILL.md
    │
    ├── references/
    │   ├── research-methodology.md
    │   ├── source-evaluation.md
    │   └── evidence.md
    │
    ├── scripts/
    │   ├── validate-sources.js
    │   └── generate-report.js
    │
    ├── templates/
    │   └── report.md
    │
    └── examples/
        ├── example-1.md
        └── example-2.md

Each part has a job.

`SKILL.md` Is the Hub

Think of SKILL.md as the router and operating manual.

It should explain:

What this skill does
When it activates
What it must accomplish
What references to load
What workflow to follow
What constraints apply
How to validate the result

It should not necessarily contain every piece of knowledge.

Hub-and-Spoke Architecture

                   SKILL.md
                  /   |                    /    |                    ↓     ↓     ↓
          References Scripts Templates

The hub provides orchestration.

The spokes provide specialized resources.

Data vs Instructions vs Code

Separate them:

Instructions

SKILL.md

Tell the agent what to do.

Data

references/

Provide knowledge.

Code

scripts/

Perform deterministic operations.

This separation makes skills easier to maintain and test.

8. Chapter 05 — Writing the Content

Now we reach the instruction layer.

Compare:

Weak

You might want to check whether tests pass.

Strong

Run the test suite before declaring the task complete.

Stronger

Do not declare the task complete until the test suite passes.

The difference is binding strength.

Instructions Have Different Authority

Preference

Prefer TypeScript.

Requirement

Use TypeScript for new files.

Hard constraint

Do not create JavaScript files. New implementation files must use TypeScript.

Important rules should be unambiguous.

Present-Tense Instructions

Instead of:

The agent should inspect the repository.

write:

Inspect the repository before making changes.

Instead of:

The agent will run the tests after implementation.

write:

Run the tests after implementation.

Direct instructions are easier to interpret.

Don't Overload the Skill With Philosophy

Avoid thousands of words explaining philosophy.

Prefer operational instructions:

1. Inspect X.
2. Determine Y.
3. Run Z.
4. If Z fails, investigate.
5. Do not proceed until Y is verified.

The skill should be operational.

9. Chapter 06 — Enforcement

This is one of the most important ideas.

Don't rely on the model to enforce something that software can enforce.

Suppose your skill says:

Always run Prettier.

The agent might comply.

But it might also forget.

A stronger design is:

AI modifies file
      ↓
Hook
      ↓
Prettier
      ↓
Formatted file

Formatting no longer depends entirely on model memory.

AI Instructions vs Mechanical Enforcement

Consider:

Never commit secrets.

A prompt can say:

RULE:
Never commit API keys.

But a stronger architecture is:

Agent
  ↓
git commit
  ↓
secret scanner
  ↓
Secret found?
  ├── Yes → Block commit
  └── No  → Continue

Enforcement Hierarchy

A useful model is:

Human judgment
      ↓
AI instruction
      ↓
Automated validation
      ↓
Mechanical enforcement

The further down the stack you go, the less you rely on model compliance.

Examples of good candidates for automation:

Formatting
Linting
Type checking
Schema validation
Tests
Secret detection
File naming
Generated artifacts
SQL safety
Permission boundaries

The AI should focus on tasks requiring judgment.

10. Chapter 07 — Measurement

Now ask:

How do we know the skill works?

A skill should ideally be evaluated, not merely read and trusted.

There are two major dimensions.

Activation Evaluation

Did the correct skill activate?

Example:

Prompt:
"Create a PostgreSQL migration for the users table."

Expected:
database-migration → activated

You can maintain an evaluation set:

┌────────────────────────────────────┐
│ Activation Evaluation              │
├────────────────────────────────────┤
│ Prompt                             │
│ Expected skill                     │
│ Should activate?                   │
│ Actual skill                       │
│ Result                             │
└────────────────────────────────────┘

Behavior Evaluation

Once activated, did the skill behave correctly?

Suppose the migration skill requires:

Inspect schema
Check migration history
Create migration
Validate SQL
Test migration
Test rollback

Behavior evaluation checks those requirements.

                    Skill
                      ↓
             ┌────────┴────────┐
             ↓                 ↓
       Activation          Behavior
             ↓                 ↓
        Correct skill?    Correct workflow?

A skill could have:

90% activation accuracy
40% behavior accuracy

and still be a poor skill.

Measuring Skills Like Software

Useful metrics include:

Activation accuracy

correct activations / total activation tests

False positive rate

incorrect activations / total tests

False negative rate

missed activations / applicable tests

Task success rate

successful executions / total executions

Rule compliance

required behaviors satisfied / required behaviors

Regression rate

previously passing cases now failing

This turns skill development into an engineering discipline.

11. Auditing Against Prior Art

Another useful activity is comparing your skill against existing approaches.

Suppose you create:

deep-research

Before declaring it complete, ask:

What existing research workflows already exist?

What evaluation techniques do they use?

What source-quality rules are common?

What am I missing?

Which practices are unnecessarily complicated?

This is prior-art auditing.

You don't need to reinvent every workflow.

12. Chapter 08 — Shipping

A skill isn't useful if nobody can install it.

A typical flow is:

Development
    ↓
Repository
    ↓
Package / Plugin
    ↓
Distribution
    ↓
Installation
    ↓
Skill available

Plugin Binding

A plugin can act as a distribution container:

Plugin
│
├── Skills
│   ├── research
│   ├── testing
│   └── code-review
│
├── Hooks
├── Commands
└── Configuration

This lets users install a cohesive collection rather than manually copying individual files.

Versioning

Once users depend on a skill, versioning matters:

research-skill@1.0.0
research-skill@1.1.0
research-skill@2.0.0

Changing:

"prefer X"

to:

"must use X"

can change agent behavior significantly.

Therefore skill versions should be treated as meaningful behavioral versions.

Dormancy

A skill may sit unused for months.

Then:

Developer
   ↓
invokes old skill
   ↓
framework changed
   ↓
skill behaves differently

This is skill dormancy.

Skills need lifecycle states and maintenance expectations.

13. Chapter 09 — Maintenance

AI skills exist inside rapidly changing ecosystems.

Things change:

AI models
Agent runtimes
APIs
CLI tools
Frameworks
Repository structures
Tool interfaces
Best practices
Security requirements

Therefore:

A skill is software, and software drifts.

Drift

Suppose:

Tool v1
 ↓
Skill v1

Later:

Tool v2
 ↓
behavior changed

Your skill still assumes the old behavior.

That is drift.

Vendored Knowledge

Suppose your skill contains a copy of external documentation:

external methodology
       ↓
copy
       ↓
your skill

The external source changes.

Your copy doesn't.

Now:

Upstream
   ↓
Version 3

Your skill
   ↓
Version 1

You have a maintenance obligation.

Review Gate

A good update flow is:

Upstream changes
       ↓
Detect change
       ↓
Review
       ↓
Update skill
       ↓
Run evaluation suite
       ↓
Check regressions
       ↓
Release

Not:

Upstream changed
       ↓
blindly copy everything

14. Chapter 10 — The Skill Portfolio

One skill is easy.

Two are manageable.

Ten are interesting.

Fifty become an architecture problem.

You may eventually have:

skills/
├── research/
├── frontend/
├── backend/
├── database/
├── security/
├── testing/
├── performance/
├── deployment/
├── documentation/
├── architecture/
├── debugging/
└── code-review/

Now you need portfolio management.

Skill Collision

Suppose the user says:

"Review my API."

Potential matches:

api-review
backend-review
security-review
performance-review

Which one activates?

This is a collision.

If multiple skills activate, their instructions may conflict.

For example:

Skill A:
"Keep the implementation minimal."

Skill B:
"Add extensive validation."

Skill C:
"Refactor the architecture."

A skill portfolio therefore needs routing and priority policies.

Skill Granularity

How large should a skill be?

Too broad:

software-engineering

with everything inside it.

Too narrow:

read-file
write-file
check-import
check-variable
run-test

You don't want hundreds of microscopic skills.

A better structure might be:

Engineering
│
├── Research
├── Implementation
├── Testing
├── Security
└── Deployment

Each skill owns a meaningful capability.

Router Families

A router can first identify the broad family:

                  User request
                       ↓
                  Main Router
                       ↓
       ┌───────────────┼───────────────┐
       ↓               ↓               ↓
   Research        Engineering      Operations
       ↓               ↓               ↓
   Research        Backend         Deployment
   skill           Security        Monitoring
                   Testing

Instead of asking:

"Which of these 100 skills should run?"

you ask:

Which family?
     ↓
Which subcategory?
     ↓
Which skill?

Retirement

A healthy portfolio needs a retirement policy.

A skill may become obsolete because:

the underlying tool disappeared
the workflow became part of another skill
the framework changed
the skill is redundant
another skill superseded it
nobody uses it anymore

A lifecycle might be:

Experimental
     ↓
Active
     ↓
Stable
     ↓
Deprecated
     ↓
Retired

This prevents the skill directory from becoming a graveyard.

15. The Deeper Architecture: Instructions + Tools + Enforcement + Evaluation

A mature skill can be viewed as four major layers:

┌──────────────────────────────────────┐
│              SKILL                   │
│                                      │
│  ┌────────────────────────────────┐  │
│  │ Instructions                    │  │
│  │ What the agent should do       │  │
│  └────────────────────────────────┘  │
│                  ↓                   │
│  ┌────────────────────────────────┐  │
│  │ Workflow                       │  │
│  │ Route / Pipeline / Loop / Map │  │
│  └────────────────────────────────┘  │
│                  ↓                   │
│  ┌────────────────────────────────┐  │
│  │ Enforcement                    │  │
│  │ Hooks / Scripts / Tests       │  │
│  └────────────────────────────────┘  │
│                  ↓                   │
│  ┌────────────────────────────────┐  │
│  │ Evaluation                     │  │
│  │ Activation / Behavior / QA    │  │
│  └────────────────────────────────┘  │
└──────────────────────────────────────┘

This is the important shift in thinking.

A skill is not merely:

prompt → answer

It is closer to:

intent
  ↓
routing
  ↓
context
  ↓
workflow
  ↓
tools
  ↓
validation
  ↓
feedback
  ↓
result

16. Example: Building a Deep Research Skill

Suppose you want:

deep-research

Its directory could be:

deep-research/
├── SKILL.md
├── references/
│   ├── research-methodology.md
│   ├── source-quality.md
│   ├── evidence-evaluation.md
│   └── synthesis.md
├── scripts/
│   ├── validate-sources.js
│   └── generate-report.js
├── templates/
│   └── research-report.md
└── evals/
    ├── activation.json
    └── behavior.json

Step 1 — Define Scope

This skill performs structured research.

It handles:
- multi-source research
- source evaluation
- evidence synthesis
- contradiction analysis
- structured reporting

It does not handle:
- software implementation
- deployment
- generic writing

Step 2 — Define Activation

Potential activation prompts:

"Research this topic deeply."

"Investigate the current state of..."

"Compare these technologies using external sources."

"Find evidence for and against this claim."

Non-activation examples:

"Fix this React bug."

"Run the tests."

"Format this file."

Step 3 — Define the Workflow

Understand question
       ↓
Decompose question
       ↓
Identify evidence requirements
       ↓
Search
       ↓
Evaluate sources
       ↓
Extract evidence
       ↓
Cross-check claims
       ↓
Synthesize
       ↓
Write report
       ↓
Validate citations

Step 4 — Add a Loop

If two sources disagree:

Source A → Claim X
Source B → Claim Y

then:

Conflict detected
       ↓
Investigate
       ↓
Find additional sources
       ↓
Re-evaluate evidence
       ↓
Resolve / report uncertainty

Now the skill combines:

Pipeline + Loop

Step 5 — Add Mechanical Validation

Instead of only telling the AI:

"Make sure every claim has a citation."

build a validator:

Report
  ↓
Citation validator
  ↓
Missing citation?
  ├── Yes → fail
  └── No  → pass

Step 6 — Evaluate Activation

Example:

Prompt:
"Do a deep investigation into DuckDB vs PostgreSQL for analytics."

Expected:
deep-research → YES

And:

Prompt:
"Fix the DuckDB connection bug."

Expected:
deep-research → NO

Step 7 — Evaluate Behavior

For a research request:

✓ question decomposition
✓ multiple sources
✓ source quality assessment
✓ evidence extraction
✓ conflicting evidence analysis
✓ synthesis
✓ citations
✓ final report

Now regressions can be detected.

17. Applying This to an AI Engineering Harness

This model becomes especially interesting when building a larger AI development harness.

Imagine:

                    AI HARNESS
                        │
                        ↓
                  Intent Router
                        │
        ┌───────────────┼───────────────┐
        ↓               ↓               ↓
     Research       Engineering      Operations
        │               │               │
        ↓               ↓               ↓
     Skills           Skills          Skills
        │               │               │
        └───────────────┼───────────────┘
                        ↓
                     Tools
                        ↓
                  Enforcement
                        ↓
                    Evaluation
                        ↓
                    Reporting

This is much more powerful than simply having a folder full of Markdown files.

18. Skills as a Policy Execution Layer

Traditional software:

Code
 ↓
Execution
 ↓
Result

AI software:

Intent
 ↓
Skill
 ↓
Reasoning
 ↓
Tools
 ↓
Result

But production AI systems need another layer:

Intent
 ↓
Skill
 ↓
Reasoning
 ↓
Tools
 ↓
Policy
 ↓
Validation
 ↓
Result

The skill becomes a bridge between natural-language intent and deterministic engineering systems.

19. The Most Important Design Principle

If there is one idea to take away from all of this, it is:

Use AI for judgment. Use software for certainty.

Let the model handle:

Interpretation
Planning
Hypothesis generation
Trade-offs
Synthesis
Creative reasoning

Let software handle:

Formatting
Validation
Testing
Schema checking
Permissions
Secret detection
Deterministic calculations
Policy enforcement

For example:

AI:
"These three files probably need to change."

Software:
"Does the resulting code compile?"

AI:
"This migration should be safe."

Software:
"Does the migration actually execute successfully?"

AI:
"These sources support the conclusion."

Software:
"Are the required citations present?"

That division produces more reliable systems.

20. Why Skill Engineering Will Become Important

As AI agents become more capable, the bottleneck increasingly shifts away from:

"Can the model write code?"

toward:

"Can we reliably control how the model works?"

That is a different engineering problem.

We need to reason about:

Activation
Context
Permissions
Workflow
Tools
Memory
Policies
Evaluation
Regression
Versioning
Distribution

These are systems problems.

That is why skill engineering starts resembling:

software architecture
        +
prompt engineering
        +
workflow orchestration
        +
testing
        +
policy enforcement
        +
package management

21. Practical Checklist for Building a Skill

Scope

[ ] Is this actually a skill?
[ ] Could this be a rule?
[ ] Could this be a hook?
[ ] Could this be a script?
[ ] What does the skill explicitly refuse to do?

Activation

[ ] When should it activate?
[ ] When should it not activate?
[ ] What are the ambiguous prompts?
[ ] Can it collide with another skill?

Architecture

[ ] Is the workflow a route?
[ ] Pipeline?
[ ] Loop?
[ ] Map?
[ ] Combination of these?

Context

[ ] Is SKILL.md concise?
[ ] Can supporting information be loaded progressively?
[ ] Are references separated from instructions?

Enforcement

[ ] Which rules can be automated?
[ ] Which checks should be hooks?
[ ] Which checks should be scripts?
[ ] Which requirements belong in CI?

Evaluation

[ ] Does the skill activate correctly?
[ ] Does it perform the correct workflow?
[ ] Are there regression tests?
[ ] Are failure cases tested?

Shipping

[ ] Is the skill versioned?
[ ] Can another developer install it?
[ ] Is plugin/package integration defined?

Maintenance

[ ] What external dependencies can drift?
[ ] Are vendored references tracked?
[ ] Is there a review process?
[ ] Can the skill become deprecated?

Portfolio

[ ] Does it overlap with another skill?
[ ] Is the granularity appropriate?
[ ] Does the router know where it belongs?
[ ] What happens when the skill is obsolete?

22. Final Architecture

Putting everything together:

                         USER INTENT
                              │
                              ▼
                     ┌────────────────┐
                     │     ROUTER     │
                     └───────┬────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │      SKILL       │
                    │                  │
                    │ Scope            │
                    │ Instructions     │
                    │ Workflow         │
                    │ References       │
                    └────────┬─────────┘
                             │
                             ▼
                  ┌─────────────────────┐
                  │   AI REASONING      │
                  └──────────┬──────────┘
                             │
                  ┌──────────┴──────────┐
                  ↓                     ↓
             Tools / APIs          Scripts
                  │                     │
                  └──────────┬──────────┘
                             ↓
                    ┌─────────────────┐
                    │   ENFORCEMENT   │
                    │                 │
                    │ Hooks           │
                    │ Policies        │
                    │ Validators      │
                    └────────┬────────┘
                             ↓
                    ┌─────────────────┐
                    │   EVALUATION    │
                    │                 │
                    │ Activation      │
                    │ Behavior        │
                    │ Regression      │
                    └────────┬────────┘
                             ↓
                         RESULT

And around the whole system:

          ┌───────────────────────────────────┐
          │           SKILL LIFECYCLE         │
          │                                   │
          │ Version → Ship → Observe →       │
          │ Maintain → Update → Deprecate    │
          │                                   │
          └───────────────────────────────────┘

Conclusion: From Prompt Files to AI Engineering

The simplest way to build an AI skill is:

Write SKILL.md

The professional way is:

Define scope
     ↓
Define activation
     ↓
Design workflow
     ↓
Structure context
     ↓
Write instructions
     ↓
Add tools
     ↓
Mechanically enforce critical rules
     ↓
Evaluate activation
     ↓
Evaluate behavior
     ↓
Version
     ↓
Ship
     ↓
Monitor drift
     ↓
Maintain
     ↓
Retire when necessary

That is the fundamental shift.

AI skills should be treated less like prompts and more like software components.

A prompt tells an AI what you would like it to do.

A well-engineered skill defines:

when it should act,
what it should do,
what context it should consume,
how it should execute,
which rules are mandatory,
what software can enforce,
how success is measured, and
how the component evolves over time.

Once you start thinking this way, .claude/skills/ stops being a collection of Markdown files.

It becomes an AI-native software architecture layer.

The future of agent engineering is not just better prompts — it is better systems around prompts.

Your Computer Is Busy When You're Not: Building a Desktop Observability Tool with Electron

Nishikanta Ray — Sun, 23 Aug 2026 17:14:54 +0000

You close your laptop.

The screen goes dark.

You assume everything stopped.

But what if it didn't?

Maybe Docker is still transferring data.

Maybe Chrome is still downloading something.

Maybe an application is consuming CPU in the background.

Maybe your computer woke up at 3 AM, performed some background work, and went back to sleep.

Most operating systems already expose pieces of this information.

The interesting part is putting those pieces together.

That's what I wanted to explore:

Can we build an observability layer for a desktop computer using Electron?

Not another CPU/RAM widget.

Something that answers:

What is my computer actually doing?

The Idea

Imagine opening your desktop monitoring application and seeing:

TODAY
────────────────────────────────────

Computer active        7h 42m
Idle                   1h 13m
Sleep                  8h 05m

Network
↓ Download             6.8 GB
↑ Upload               1.2 GB

Top applications
────────────────────────────────────

VS Code                3h 42m
Chrome                 2h 18m
Docker                 1h 31m
Slack                  52m

Network-heavy apps
────────────────────────────────────

Docker                 2.4 GB
Chrome                 1.8 GB
VS Code                920 MB

Now imagine clicking "What happened while I was away?"

18:42  User became idle
18:51  Screen locked
18:53  Docker network activity
19:07  Background sync completed
19:14  System entered sleep

That's much more interesting than a CPU percentage.

The npm Package That Makes This Easier

Instead of writing native system integrations for everything ourselves, we can start with:

npm install systeminformation

systeminformation provides APIs for system information, CPU, memory, battery, filesystem, network, processes, Docker and more. It also supports Linux, macOS and Windows, although individual APIs have platform-specific support.

For example:

const si = require("systeminformation");

async function getSystemStats() {
  const [cpu, memory, battery, network] = await Promise.all([
    si.currentLoad(),
    si.mem(),
    si.battery(),
    si.networkStats()
  ]);

  return {
    cpu: cpu.currentLoad,
    memory: memory.active,
    battery: battery.percent,
    network
  };
}

console.log(await getSystemStats());

Now our Electron main process can periodically collect system information.

Monitoring Network Activity

One of the most useful APIs is:

si.networkStats()

It provides network statistics including received/transmitted bytes and calculated per-second rates. The package calculates rates based on differences between successive calls, so the first call doesn't provide a meaningful rate yet.

A simple monitor:

const si = require("systeminformation");

setInterval(async () => {
  const stats = await si.networkStats();

  for (const network of stats) {
    console.log({
      interface: network.iface,
      download: network.rx_sec,
      upload: network.tx_sec
    });
  }
}, 1000);

Now we have something like:

Wi-Fi
Download: 2.4 MB/s
Upload:   180 KB/s

But this is only the beginning.

Network Connections

We can also inspect active network connections:

const connections = await si.networkConnections();

console.log(connections);

This gives us information about active TCP/UDP connections.

That means we can potentially build:

Active Connections
────────────────────────────

TCP    443    api.example.com
TCP    443    github.com
TCP    443    google.com
UDP    53     DNS

Now the dashboard starts becoming useful for troubleshooting.

Which Application Is Active?

Network traffic alone doesn't tell us who is responsible.

We also want to know which application the user is interacting with.

One option is a native active-window module such as:

npm install @jannchie/active-window

The package exposes information about the currently selected window and user idle time on supported Windows, macOS and Linux/Xorg environments. Platform coverage isn't identical everywhere, so this should be treated as an OS-dependent component.

Conceptually:

const activeWindow = require("@jannchie/active-window");

async function getActiveApp() {
  const window = await activeWindow().getActiveWindow();

  return {
    process: window.windowClass,
    title: window.windowName
  };
}

Then we can record:

10:32:14  VS Code
10:32:15  VS Code
10:32:16  VS Code
...
10:45:02  Chrome
10:45:03  Chrome

Instead of storing every second individually, we can aggregate this into sessions.

VS Code
10:32 → 10:45
Duration: 13 minutes

Sleep and Wake

This is where Electron itself becomes useful.

Electron provides the powerMonitor module for monitoring system power-state changes, including suspend/resume, AC/battery changes, idle state and lock/unlock events on supported platforms.

In the Electron main process:

const { powerMonitor } = require("electron");

powerMonitor.on("suspend", () => {
  console.log("System is going to sleep");
});

powerMonitor.on("resume", () => {
  console.log("System woke up");
});

We can turn those events into database records:

function recordEvent(type) {
  db.insert({
    type,
    timestamp: new Date()
  });
}

powerMonitor.on("suspend", () => {
  recordEvent("system_sleep");
});

powerMonitor.on("resume", () => {
  recordEvent("system_wake");
});

Now our timeline knows when the machine slept.

Idle Detection

Electron also provides:

powerMonitor.getSystemIdleTime()

and:

powerMonitor.getSystemIdleState(60)

The latter can return states such as active, idle, or locked on supported systems.

For example:

const state = powerMonitor.getSystemIdleState(60);
const idleSeconds = powerMonitor.getSystemIdleTime();

console.log({
  state,
  idleSeconds
});

We can therefore distinguish:

Active
   ↓
Idle
   ↓
Locked
   ↓
Sleep

That's much more meaningful than simply measuring application runtime.

Putting Everything Together

Now imagine collecting events from four sources:

                 Electron App
                      │
       ┌──────────────┼──────────────┐
       │              │              │
  powerMonitor   systeminformation   active-window
       │              │              │
       │         CPU / RAM / Net     Active App
       │              │              │
       └──────────────┼──────────────┘
                      ▼
                Event Collector
                      │
                      ▼
                Local Database
                      │
                      ▼
              Activity Timeline

A simple event model could be:

{
  timestamp: Date.now(),
  type: "network",
  app: "docker",
  downloadBytes: 1824000,
  uploadBytes: 420000
}

Or:

{
  timestamp: Date.now(),
  type: "power",
  state: "sleep"
}

Or:

{
  timestamp: Date.now(),
  type: "application",
  app: "Code",
  window: "server.js - Visual Studio Code"
}

Now everything becomes queryable.

The Interesting Part: Correlation

This is where a normal system monitor becomes a desktop observability tool.

Suppose we see:

18:20  User idle
18:23  CPU 65%
18:24  Network 18 MB/s
18:26  Docker active
18:31  420 MB downloaded
18:42  Screen locked
18:45  Network still active
19:02  System sleep

We can generate an explanation:

Docker continued running after the user became idle and transferred approximately 420 MB before the system entered sleep.

That's an insight.

Not just a metric.

A Simple Collector

We could start with something surprisingly small:

const { powerMonitor } = require("electron");
const si = require("systeminformation");

async function collect() {
  const [cpu, memory, network] = await Promise.all([
    si.currentLoad(),
    si.mem(),
    si.networkStats()
  ]);

  return {
    timestamp: Date.now(),

    system: {
      idle: powerMonitor.getSystemIdleTime(),
      idleState: powerMonitor.getSystemIdleState(60),
      battery: powerMonitor.isOnBatteryPower()
    },

    cpu: cpu.currentLoad,

    memory: {
      active: memory.active,
      total: memory.total
    },

    network: network.map(n => ({
      interface: n.iface,
      rxPerSecond: n.rx_sec,
      txPerSecond: n.tx_sec
    }))
  };
}

setInterval(async () => {
  console.log(await collect());
}, 5000);

Five seconds later, we have the beginning of our own desktop telemetry system.

But Don't Collect Everything Every Second

This is an important design decision.

You don't necessarily want:

Every 1 second
    ↓
Everything
    ↓
Database

That can generate enormous amounts of useless data.

Instead, use different collection intervals.

Power events        Event-driven
App changes         Event-driven
CPU                 5-10 seconds
Memory              10 seconds
Network             1-5 seconds
Connections         10-30 seconds
Daily aggregates    1 minute+

And store state changes rather than repeated identical states.

For example, don't write:

10:00 VS Code
10:01 VS Code
10:02 VS Code
10:03 VS Code
10:04 VS Code

Store:

VS Code
10:00 → 10:04
Duration: 4 minutes

This makes the database dramatically smaller.

What About Electron's Network Logging?

If the thing you're monitoring is specifically your Electron application's own network traffic, Electron has another useful tool: netLog.

const { app, netLog } = require("electron");

app.whenReady().then(async () => {
  await netLog.startLogging("/tmp/electron-network-log");
});

Electron's netLog records network events for a session and supports different capture modes. Be careful with includeSensitive and everything, because those modes can capture sensitive information or transferred bytes.

This is different from systeminformation:

systeminformation
        ↓
Whole-system information

Electron netLog
        ↓
Your Electron application's network activity

That distinction is important.

The Product I Would Build

I wouldn't call this another "Task Manager."

I'd call it something like:

Desktop Observability

The dashboard could have four major views.

1. Activity

VS Code       4h 12m
Chrome        2h 31m
Slack         58m
Docker        1h 42m

2. Network

Download     8.4 GB
Upload       1.3 GB

Docker       3.1 GB
Chrome       2.7 GB
VS Code      1.2 GB

3. Power

Active       8h 21m
Idle         1h 08m
Sleep        7h 42m

Battery used 34%

4. Timeline

09:02  Wake
09:05  VS Code
10:32  Chrome
12:14  Idle
12:31  Docker network activity
13:02  Active
18:42  Lock
19:01  Sleep

And then the killer feature:

Ask the computer

Why was my laptop slow today?

What used the most bandwidth?

What happened while I was away?

Which applications are active in the background?

Did anything continue running after I locked the computer?

The Architecture

A practical first version could be:

Electron
│
├── Main Process
│   │
│   ├── powerMonitor
│   ├── systeminformation
│   ├── active-window
│   └── netLog
│
├── Collector
│   │
│   ├── power events
│   ├── app sessions
│   ├── CPU/memory
│   └── network stats
│
├── SQLite
│
└── React Renderer
    │
    ├── Dashboard
    ├── Timeline
    ├── Applications
    ├── Network
    └── Power

The key design principle is:

Collect locally. Correlate locally. Explain locally.

You don't need to send a user's entire computer activity to a cloud server just to tell them why their laptop was busy.

The Bigger Idea

The interesting thing here isn't systeminformation.

It isn't Electron's powerMonitor.

It isn't network monitoring.

It's the combination.

A computer is already generating thousands of signals:

Applications
Processes
CPU
Memory
Network
Power
Sleep
Wake
Idle
Lock
Unlock

Today, these signals are mostly presented independently.

A desktop observability layer could connect them.

And instead of asking:

"What's my CPU usage?"

we can finally ask:

"What happened on my computer while I wasn't looking?"

That's a much more interesting monitoring problem.

Smashing the "Blind Spot" Bug: How We Integrated Sentry to Catch Regressions in Real-Time

Nishikanta Ray — Sat, 08 Aug 2026 20:38:12 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories powered by Sentry.

The Challenge: Flying Blind in Production

Pull Request - https://github.com/NishikantaRay/InsightTrack/commit/a70ca0a00c8cd169a93b300cfcb450b5ecbde7f8

Before this summer, our analytics platform, InsightTrack, had a fundamental flaw in how it handled observability. We were tracking standard JavaScript errors via a basic window.onerror handler, but it was just noise. We had no stack traces, no grouped fingerprints, and absolutely no release context.

If a customer integrated 10 different sites into our platform, we couldn't accurately tell them if a specific spike in errors was a brand-new issue or a resurrected bug from three deployments ago. We were flying blind, and our users were feeling the pain of delayed bug resolutions.

The ultimate "bug" wasn't a single line of broken code; it was our entire error observability pipeline.

The Solution: A Deep-Dive Sentry Integration

We decided to smash this architectural bug by building a native, robust integration with Sentry. We didn't just want to add a widget; we wanted to bring Sentry's rich context (fingerprinted grouping, permalinks, regression status, and user-impact counts) directly into the InsightTrack dashboard so traffic and bugs could be watched side-by-side.

How We Built It

To make this work seamlessly at scale (where one customer might poll 10 independent Sentry projects simultaneously), we built a dual-path ingestion system:

The Polling Backstop: We set up a bounded worker pool (to prevent slow projects from stalling the fleet) that polls the Sentry API every 5 minutes. To respect rate limits, we built an adaptive cadence—active projects poll frequently, while quiet or erroring projects exponentially back off.
The Near-Real-Time Webhook: For instant visibility, we allowed users to point a Sentry Internal Integration webhook at our API. Using HMAC signatures verified in constant time against a stored secret, new or regressed issues hit our database in milliseconds.

The Golden Rule of our Architecture:
All writes (polls and webhooks) go to PostgreSQL. A background sync then pushes this data to DuckDB every 60 seconds. All dashboard reads and analytics queries come only from DuckDB for lightning-fast performance.

The "Smash" Moment 🔨

We deployed the Sentry integration to production on a Tuesday. On Wednesday morning, it paid off spectacularly.

A customer pushed a massive UI update to their e-commerce site. Within three minutes, our newly built Error Spike Alerts—which calculate a 2-sigma (2σ) z-score against a 7-day rolling mean of Sentry events—fired off an alarm in their dashboard.

Because we were pulling in Sentry's substatus API field, the issue surfaced with a glaring red Regressed badge right in our UI.

Instead of opening five different tabs to figure out what went wrong, the customer clicked the row in our dashboard. This triggered our Live Drill-Down feature, which makes an on-demand, real-time fetch directly to Sentry's /events/latest/ endpoint. The stack trace, breadcrumbs, and tags populated instantly.

The bug? A deprecated checkout component that had been accidentally uncommented during a merge conflict. It was identified, patched, and deployed before most of their users even woke up.

What I'm Proud Of

I am incredibly proud of how resilient we made this system. By decoupling the write path (PostgreSQL) from the read path (DuckDB), the dashboard remains incredibly fast even if the polling workers are churning through thousands of Sentry pagination cursors in the background.

I'm also proud of the AI Analyst (Pulse) tools we built on top of this. Because the data is so cleanly structured in DuckDB, we exposed read-only MCP tools (get_error_summary and get_error_issues). Now, users can literally chat with their analytics dashboard and ask, "Did yesterday's deploy cause any regressions?" and the AI will read the synced Sentry data to give them a perfect answer.

What I Learned

Handling external APIs requires defensive programming. Assuming an API will always return what you expect is a recipe for disaster. Building in graceful degradation and adaptive backoffs (like dropping to a 6-hour poll cadence on a 401 Auth Fail) kept our system from DDOSing ourselves with bad tokens.
Webhooks + Polling = The perfect marriage. Webhooks are great for speed, but polling is necessary for accurate counts and state reconciliation (e.g., soft-deleting issues that have aged out). Using both gives you the best of both worlds.

Thanks to Sentry and the DEV community for the motivation to finally smash this architectural bug!

The ultimate "bug" wasn't a single line of broken code; it was our entire error observability pipeline.
Github - https://github.com/nishikantaray/InsightTrack
Website - https://insightstrack.dev
Pull Request - https://github.com/NishikantaRay/InsightTrack/commit/a70ca0a00c8cd169a93b300cfcb450b5ecbde7f8
Portfolio - https://nishikanta.in/

Building an AI-native Second Brain with Multi-RAG, Knowledge Graphs, and MCP

Nishikanta Ray — Sat, 08 Aug 2026 02:38:21 +0000

Claude is incredibly good at reasoning.

But reasoning is only as useful as the context available to it.

Your architecture might be in GitHub. Your notes might be in Obsidian. Your decisions might be buried in Slack. Your research might be in PDFs. Your project history might exist across hundreds of conversations.

The information exists.

The problem is that your AI doesn't have a unified way to understand it.

So I started thinking:

What if Claude had a persistent Second Brain?

Not another chatbot. Not another vector database.

A knowledge layer that Claude can query, learn from, and write back to.

What Is a Second Brain?

A Second Brain is a personal knowledge management system that helps you capture, organize, connect, and retrieve information outside your biological memory.

Tools like Obsidian made this idea powerful.

You can write simple Markdown notes and connect them:

InsightTrack
    │
    ├── [[DuckDB]]
    ├── [[PostgreSQL]]
    └── [[MCP]]

Obsidian then creates a visual graph of those relationships.

But there is a limitation:

Obsidian knows the relationships you explicitly create.

AI can take this much further.

Imagine having:

architecture.md
      │
      └── mentions DuckDB

GitHub PR #481
      │
      └── changes DuckDB queries

Slack discussion
      │
      └── explains why DuckDB was selected

benchmark.md
      │
      └── contains performance results

A human may never manually connect all four.

An AI-native knowledge system can discover those relationships automatically.

From Second Brain to AI Brain

A traditional Second Brain mainly answers:

"Where did I save this?"

An AI-native Second Brain should answer:

"What do we know about this, where did it come from, and how is it connected to everything else?"

That requires more than vector search.

It requires multiple retrieval strategies working together.

Why Traditional RAG Isn't Enough

A typical RAG architecture looks like:

Documents
    ↓
Chunking
    ↓
Embeddings
    ↓
Vector Search
    ↓
LLM

This works extremely well for semantic similarity.

Ask:

"What was the reasoning behind our analytics architecture?"

Vector search can find relevant discussions even if the exact wording is different.

But now ask:

"Where is SYNC_BATCH_SIZE defined?"

That's an exact identifier.

Keyword search is better.

Or ask:

"What services depend on PostgreSQL?"

That's a relationship question.

A knowledge graph is better.

This is why I think a serious AI Second Brain needs Multi-RAG.

Multi-RAG: Different Questions Need Different Retrieval

Instead of relying on one retrieval technique:

Semantic Search
       +
Full-Text Search
       +
Knowledge Graph
       +
Metadata Filtering
       +
Reranking

Each method solves a different problem.

Semantic RAG

Good for understanding concepts.

"Why did we choose DuckDB?"

Keyword RAG

Good for exact information.

"Find references to SYNC_BATCH_SIZE."

Graph RAG

Good for relationships.

"Which services depend on PostgreSQL?"

Memory Retrieval

Good for decisions and persistent context.

"What did we decide about the analytics architecture?"

Together, they provide much richer context than vector search alone.

The Architecture

The important idea isn't any individual component.

It's how the components work together.

Obsidian / Documents / External Sources
                │
                ▼
           Event Queue
                │
                ▼
        Processing Workers
          │      │      │
          ▼      ▼      ▼
       Metadata Embedding Graph
          │      │      │
          └──────┼──────┘
                 ▼
          Knowledge Layer
                 │
      ┌──────────┼──────────┐
      ▼          ▼          ▼
   Vector      Search      Graph
   Search      Index       Store
      │          │          │
      └──────────┼──────────┘
                 ▼
          Retrieval Engine
                 │
                 ▼
              MCP / API
                 │
                 ▼
          Claude / GPT / AI

Obsidian Is the Human Interface

I don't see Obsidian as the entire Second Brain.

I see it as one of the best human-facing knowledge interfaces.

You can continue writing naturally:

# Analytics Architecture

InsightTrack uses [[DuckDB]] for analytical queries.

Data originates in [[PostgreSQL]].

See [[Pulse]] for the AI analytics layer.

Obsidian gives you human-readable notes and a native graph.

The AI system adds another layer on top.

Two Graphs, Two Purposes

This architecture can maintain two different graphs.

Obsidian Graph

Created from explicit links:

[[InsightTrack]]
       │
       ▼
   [[DuckDB]]
       │
       ▼
  [[Analytics]]

This is primarily useful for human navigation.

System Entity Graph

Automatically extracted from all available knowledge:

InsightTrack
      │
     USES
      │
   DuckDB
   /    \
READS   SYNCED_FROM
 /          \

Pulse PostgreSQL

The system graph can be built from:

Markdown
Source code
Git commits
Pull requests
Database schemas
Documentation
Conversations
Meeting notes

This graph isn't just for visualization.

It becomes part of retrieval.

Knowledge Engineering + Graph Engineering

This is where the architecture becomes more interesting than a normal RAG application.

Knowledge Engineering turns raw information into structured knowledge.

Meeting Transcript
        ↓
     Summary
        ↓
   Action Items
        ↓
Architecture Decision
        ↓
   Project Memory

Graph Engineering connects the resulting entities.

Project
   ↓
Repository
   ↓
  API
   ↓
Database
   ↓
Developer
   ↓
Decision

The result isn't just a collection of documents.

It's a connected knowledge model.

The Retrieval Engine

The retrieval engine is arguably the most important part.

Suppose you ask:

Why did we move analytics queries from PostgreSQL to DuckDB?

The system might retrieve:

GitHub PR
      +
Architecture Note
      +
Benchmark
      +
Slack Discussion
      +
Decision Memory

Then rerank and combine the results.

Instead of giving Claude thousands of chunks, the system builds a focused context:

Decision:
Use DuckDB for analytical workloads.

Evidence:
- Benchmarks showed better aggregation performance.
- PostgreSQL remains the transactional source of truth.
- The architecture PR implemented the separation.
- The Slack discussion explains the operational trade-offs.

Now Claude is reasoning over evidence + relationships + memory.

Long-Term Memory

A Second Brain shouldn't remember everything.

Otherwise, it becomes another giant database.

It should remember what matters.

For example:

Decision
────────────────────
PostgreSQL remains the source of truth.

Decision
────────────────────
DuckDB handles analytical reads.

Reason
────────────────────
Better analytical performance and isolation.

Status
────────────────────
Implemented.

This is much more valuable than storing thousands of raw conversations.

The system should distinguish between:

Raw Data
   ↓
Information
   ↓
Knowledge
   ↓
Memory

That's an important part of making AI memory useful.

MCP Connects the Second Brain to Claude

This is where the architecture becomes AI-native.

Instead of building a custom integration directly into Claude, expose the Second Brain through MCP.

For example:

search()
retrieve()
remember()
ingest()
graph()
timeline()

Claude can ask:

search(
  "Why did we choose DuckDB?"
)

The Second Brain handles the complexity.

Claude doesn't need to know whether the answer came from:

PostgreSQL
pgvector
Search Index
Knowledge Graph
Obsidian
GitHub
Slack

It simply receives useful context.

Claude Can Write Back

This is where it becomes more than traditional RAG.

The flow isn't only:

Knowledge → AI

It becomes:

Knowledge ↔ AI

For example:

"Remember that we decided to keep PostgreSQL as the source of truth."

Claude calls:

remember(...)

The system can then:

Extract Entities
       ↓
Extract Relationships
       ↓
   Create Memory
       ↓
Generate Embedding
       ↓
   Update Graph
       ↓
   Store Source

The knowledge base becomes progressively richer.

The Model Doesn't Own the Knowledge

This is one of the most important ideas.

Today:

Claude
   ↓
Claude Memory

Another AI:

GPT
   ↓
GPT Memory

Another:

Gemini
   ↓
Gemini Memory

Everything is isolated.

Instead:

             Claude
                │
               GPT
                │
             Gemini
                │
              Cursor
                │
                ▼
         ┌───────────────┐
         │  Knowledge OS │
         └───────────────┘

The model can change.

The knowledge stays.

The Bigger Idea

I don't think the future is simply:

"Give Claude more context."

I think it's:

Build a persistent knowledge layer that every AI can use.

Obsidian can remain your human knowledge interface.

GitHub can remain your source-code system.

Slack can remain your communication system.

Your databases can remain your data systems.

Your AI assistants can remain your reasoning systems.

The Knowledge OS connects them.

Beyond the Second Brain

A traditional Second Brain helps you remember.

An AI-native Second Brain helps AI understand.

It combines:

Knowledge Engineering — turning raw information into structured knowledge
Graph Engineering — discovering entities and relationships
Hybrid Retrieval — combining semantic, keyword, and graph search
Long-Term Memory — preserving decisions and important context
MCP — making the knowledge available to AI agents and assistants

The result is something larger than a note-taking application or a vector database.

An AI-native Knowledge Operating System that combines Knowledge Engineering, Graph Engineering, Hybrid Retrieval, and Long-Term Memory into a unified platform accessible through MCP and APIs.

The LLM provides the reasoning.

The Knowledge OS provides the memory.

And MCP becomes the bridge between them.

Mind Maps in MCP: A Powerful Feature or Just Eye Candy?

Nishikanta Ray — Sat, 01 Aug 2026 18:27:45 +0000

Mind maps are an excellent addition to an MCP ecosystem when they help users understand relationships between data, tools, and reasoning. They should complement—not replace—traditional dashboards, tables, and chat interfaces.

Introduction

Large Language Models have become incredibly good at answering questions. Ask about your analytics, codebase, documentation, or infrastructure, and they'll generate a detailed response in seconds.

But there's a problem.

Most AI conversations are linear, while the problems we're solving are non-linear.

Imagine asking:

Why did traffic drop yesterday?

A traditional AI responds with several paragraphs of text.

A mind map, however, immediately shows the relationships between traffic sources, landing pages, countries, devices, deployments, and JavaScript errors.

Instead of reading hundreds of words, you understand the entire situation in seconds.

This naturally raises an interesting question:

Should every MCP server support mind maps?

After exploring different architectures and use cases, my conclusion is simple:

Yes—but only when they help users understand relationships rather than simply displaying information.

Let's explore why.

What is a Mind Map in MCP?

An MCP (Model Context Protocol) server exposes tools that AI models can use.

Normally the workflow looks like this:

User
  │
  ▼
LLM
  │
  ▼
MCP Tool
  │
  ▼
Database
  │
  ▼
Response

The AI collects data, summarizes it, and returns text.

Now imagine adding a visualization layer.

             User
               │
               ▼
          AI Planner
               │
      ┌────────┴────────┐
      ▼                 ▼
 Analytics Tool    Documentation Tool
      ▼                 ▼
 Error Tool        Code Search Tool
      ▼                 ▼
      └────────┬────────┘
               ▼
     Relationship Builder
               ▼
      Interactive Mind Map

The AI still performs the same work.

The difference is that users now see how everything connects instead of reading a long explanation.

Why Traditional AI Isn't Always Enough

Humans naturally think in relationships.

When someone asks:

Why are conversions down?

They aren't thinking linearly.

They're exploring multiple possibilities simultaneously.

Conversions
│
├── Traffic
│
├── Checkout
│
├── Marketing
│
├── Performance
│
├── Returning Users
│
└── Errors

Each branch creates another investigation.

This is exactly how troubleshooting works.

A mind map simply visualizes that thought process.

Real Analytics Example

Suppose an AI receives this question:

Why did yesterday's traffic decrease?

Instead of returning paragraphs, it could generate something like:

Traffic Drop
│
├── Organic Search ↓
│
├── Homepage ↓
│
├── India ↓
│
├── JavaScript Errors ↑
│
├── Core Web Vitals ↓
│
└── New Deployment ✓

Within seconds the user understands:

Organic search decreased
Homepage was affected
Most impact came from India
JavaScript errors increased
A deployment happened recently

The graph immediately tells a story.

Where Mind Maps Work Best

1. Analytics Investigation

Traditional dashboards answer:

How many visitors?
Which country?
Which browser?

Mind maps answer:

Why did traffic change?
Which metrics influence each other?
What caused this anomaly?

Example:

Traffic
│
├── Organic
│   ├── Landing Pages
│   ├── Keywords
│   └── Countries
│
├── Paid
│
├── Social
│
└── Referral

This transforms disconnected metrics into connected insights.

2. Documentation Search

Imagine asking:

Explain authentication.

Instead of returning dozens of documents, the AI groups concepts together.

Authentication
│
├── OAuth
├── JWT
├── API Keys
├── Sessions
└── Permissions

Users instantly understand the overall architecture.

3. Codebase Exploration

Large repositories can be overwhelming.

Instead of thousands of files:

Backend
│
├── API
│
├── Database
│   ├── PostgreSQL
│   └── Prisma
│
├── Authentication
│
└── Workers

Developers can navigate the repository visually.

4. AI Agent Planning

Most AI agents perform many hidden steps.

A mind map exposes them.

Task
│
├── Research
│
├── Search
│
├── Compare
│
├── Generate
│
└── Validate

This makes debugging AI workflows dramatically easier.

The Biggest Advantages

Better Understanding

Humans recognize patterns much faster than paragraphs.

Instead of reading 800 words, users understand the entire structure in seconds.

Relationship Discovery

Traditional dashboards display numbers.

Mind maps display relationships.

For example:

Deployment
      │
      ▼
JavaScript Errors
      │
      ▼
Checkout Failure
      │
      ▼
Revenue Drop

That chain is much harder to discover from charts alone.

Easier Navigation

Users don't need every detail immediately.

They can expand only the sections they care about.

Traffic
  │
  ├── Organic
  │
  ├── Direct
  │
  └── Social

This keeps complex systems manageable.

Better AI Transparency

Instead of wondering why the AI reached a conclusion, users can inspect the reasoning path visually.

This increases trust in AI-generated answers.

Where Mind Maps Fail

Like every visualization, they have limitations.

Everything Becomes a Graph

One common mistake is trying to visualize every piece of information.

Imagine this:

Visitors
│
├── Countries
├── Browsers
├── Devices
├── Sessions
├── Events
├── Campaigns
├── Pages
├── Heatmaps
├── Errors
├── Funnels
├── Scroll Depth
├── UTM
├── Performance
└── ...

After a few hundred nodes, the graph becomes unreadable.

Tables Are Sometimes Better

Suppose someone asks:

Show today's visitors.

They don't need a graph.

They need this:

Hour	Visitors
9 AM	241
10 AM	318
11 AM	401

Not every question benefits from visualization.

Performance

Large graphs become expensive.

Some challenges include:

Thousands of nodes
Complex edge calculations
Layout algorithms
Browser memory usage
Slow rendering

Most graph libraries begin struggling once graphs become extremely large unless clustering or virtualization is implemented.

Additional Maintenance

Relationships don't build themselves.

Every new feature means:

New node types
New edge rules
Updated layouts
Better ranking algorithms

Graph maintenance quickly becomes its own subsystem.

Common Mistakes

Many developers build graphs that simply mirror database tables.

Example:

Country
   │
   ▼
India
   │
   ▼
Users
   │
   ▼
5000

That provides almost no value.

Instead, focus on relationships.

Example:

Traffic Drop
│
├── Homepage
├── Organic Search
├── India
└── JavaScript Errors

The graph explains why something happened.

Should Every MCP Include Mind Maps?

Not necessarily.

Here's a simple rule.

Great Fit	Poor Fit
Documentation	Raw SQL
AI reasoning	CSV exports
Research	Tables
Architecture	Dashboards
Agent workflows	Metric reports
Knowledge graphs	Simple searches

Mind maps are strongest when users need to understand connections, not just retrieve information.

A Better Architecture

Rather than replacing the existing interface, add mind maps as an exploration mode.

Dashboard
│
├── Visitors
├── Revenue
├── Funnels
├── Heatmaps
└── Errors

        │
        ▼

🧠 Explore Relationships

        │
        ▼

Traffic
│
├── Acquisition
├── Geography
├── Pages
├── Errors
└── Performance

The dashboard remains familiar.

The graph becomes a discovery tool.

This hybrid approach gives users the best of both worlds.

Recommended Libraries

If you're planning to build interactive graph visualizations, these libraries are worth considering.

React Flow

Perfect for:

Interactive editors
Expandable nodes
Workflow builders
AI reasoning graphs

Cytoscape.js

Excellent for:

Large relationship graphs
Knowledge visualization
Network analysis

AntV G6

Great for:

Enterprise dashboards
Knowledge graphs
Automatic layouts

Sigma.js

Designed for:

Very large graphs
High-performance rendering
Thousands of nodes

D3.js

Ideal when you need complete customization and don't mind writing more code.

My Recommendation

If I were designing an MCP platform today, I wouldn't make the mind map the default interface.

Instead, I'd treat it as an optional exploration layer.

Users should still have access to:

Traditional chat
Tables
Dashboards
Charts
SQL results

When they want to understand relationships, they can switch to the graph view.

This keeps the interface simple while providing powerful visualization when it's genuinely useful.

Final Thoughts

Mind maps aren't valuable because they look impressive.

They're valuable because they help users understand relationships that are difficult to see in text, tables, or dashboards.

For MCP ecosystems, they're especially effective for:

AI reasoning
Documentation discovery
Codebase exploration
Knowledge graphs
Multi-agent workflows
Analytics investigations

However, they should never replace dashboards or structured data.

The most effective MCP platforms will combine both approaches:

Chat for conversations
Dashboards for metrics
Mind maps for relationships

Use each interface where it excels.

In the end, the goal isn't to make AI prettier—it's to make complex information easier to understand.

Running Hermes Agent with Kokoro TTS: A Local-First AI Assistant Setup

Nishikanta Ray — Sun, 26 Jul 2026 07:19:14 +0000

Most AI agents today depend heavily on cloud APIs. They're fast, but every request costs money, depends on an internet connection, and sends your data to external providers.

Over the weekend, I experimented with Hermes Agent and Kokoro TTS, building a completely local voice-enabled AI assistant. The result was surprisingly good—responses were generated locally, converted into natural speech, and even delivered through Telegram.

It felt much closer to having a personal AI operating system than simply chatting with an LLM.

What is Hermes Agent?

Hermes Agent is an open-source AI agent framework from Nous Research designed for long-running AI workflows. Unlike a traditional chatbot, Hermes can:

Execute tools
Remember previous interactions
Learn reusable skills
Schedule recurring jobs
Connect with messaging platforms like Telegram
Work with both cloud and local models

It also supports OpenAI-compatible endpoints, making it easy to swap between cloud providers and local inference engines.

Why use Kokoro TTS?

Kokoro is a lightweight text-to-speech engine that runs locally and produces surprisingly natural voices.

Instead of sending text to cloud TTS providers, everything happens on your own machine.

Benefits

Completely offline
No API costs
Low latency
Privacy-friendly
Easy integration with local AI workflows

For demos, assistants, and automation, it feels almost instant.

Architecture

                User
                  │
          Telegram / CLI
                  │
          ┌───────────────┐
          │ Hermes Agent  │
          └──────┬────────┘
                 │
      ┌──────────┴──────────┐
      │                     │
 Local LLM             Tool Calls
(Qwen/Llama/etc.)      Browser/MCP/etc.
      │
      ▼
 Response Text
      │
      ▼
 Kokoro TTS
      │
      ▼
 Natural Voice
      │
      ▼
 Telegram Voice Message

The same response can be delivered as:

Text
Voice
Or both simultaneously

Why run locally?

A local-first setup offers several advantages:

Privacy

Sensitive conversations never leave your machine unless you explicitly enable external tools.

Zero inference cost

After downloading the models, you no longer pay per request.

Faster iteration

Developers can test prompts, agents, and automations without worrying about API limits.

Offline capability

Useful for demos, labs, or environments with limited internet access.

Typical Setup

A common local stack looks like this:

Hermes Agent
Ollama or another OpenAI-compatible local model server
Kokoro TTS
Telegram Gateway (optional)
MCP servers
Local memory and skills

Hermes can connect to local model servers such as Ollama, LM Studio, vLLM, llama.cpp, and other OpenAI-compatible endpoints.

Real Use Cases

Personal AI Assistant

Ask questions and receive spoken replies.

Coding Agent

Read repositories, execute tools, and explain code aloud.

Customer Support Bot

Generate text and voice responses without cloud inference costs.

Home Automation

Control local services with voice feedback.

Content Creation

Generate narration for tutorials, demos, podcasts, and videos.

Research Assistant

Summarise documents and listen instead of reading long reports.

Pros

✅ Local inference

✅ Better privacy

✅ No recurring API costs

✅ Natural voice responses

✅ Works with existing OpenAI-compatible APIs

✅ Flexible model switching

✅ Extensible through tools and skills

Cons

❌ Requires decent CPU/GPU resources

❌ Initial model downloads can be large

❌ Local models may be slower than premium cloud models

❌ Voice quality depends on the selected TTS model

❌ Some external tools (web search, browser automation, cloud speech) still require internet access if enabled.

Who should use this?

This setup is ideal for:

AI developers
Open-source enthusiasts
Privacy-conscious users
Local LLM experimentation
Voice assistant projects
Internal enterprise tooling

If you're already using MCP servers or self-hosted AI infrastructure, Hermes integrates naturally into that workflow.

Final Thoughts

Hermes Agent combined with Kokoro TTS creates a surprisingly capable local AI assistant. Instead of just generating text, the system can reason, use tools, remember context, and respond with natural speech—all while keeping inference largely on your own machine.

For developers building AI assistants, coding agents, research tools, or voice-enabled applications, this local-first stack offers an excellent balance between privacy, flexibility, and cost.

After experimenting with it over the weekend, it's easy to see why local AI workflows are becoming increasingly practical. Cloud models still have their place for the hardest reasoning tasks, but for many day-to-day workflows, a local setup is already more than capable.

InsightsTrack + Pulse: I taught Claude Desktop to read my web analytics (via MCP)

Nishikanta Ray — Sun, 12 Jul 2026 15:01:53 +0000

This is a submission for Weekend Challenge: Passion Edition

What I Built

InsightsTrack is a self-hosted, privacy-first web analytics platform — the open-source alternative to Google Analytics. No cookies, no consent banner, no data selling. You run it on your own server and get real-time visitors, funnels, heatmaps, Core Web Vitals, and 17+ analytics views.

But the part I'm passionate about — and the reason I'm submitting it here — is Pulse: a built-in AI analyst that turns your analytics into a conversation.

Instead of hunting through dashboards, you just ask:

"What were my top pages last week?"
"Where is my traffic coming from?"
"Where are users dropping off in the funnel?"

Pulse answers in plain English, with real charts, tables, and CSV exports — every number backed by a live tool call, never hallucinated.

And here's the passion project twist: Pulse isn't locked inside the dashboard. The same analytics tools are exposed over MCP (Model Context Protocol), so I can open Claude Desktop, Cursor, or any MCP client and ask it about my website traffic — and it queries InsightsTrack directly.

My goal: make your own analytics as easy to query as sending a text message — and make that capability portable to every AI tool you already use.

Demo

🔗 Live app: https://insightstrack.dev
▶️ Video walkthrough: https://youtu.be/LGZw8temtPY

What to show in the demo:

Open the dashboard, click Ask Pulse, type "top pages last 7 days" → watch it stream an answer + render a table with a CSV button and an Open pages → deep link.
Switch the same result between table / bar / line / donut with one click.
Open Claude Desktop → ask "which sites do I have in InsightsTrack, and what's my top traffic source this month?" → it calls the MCP tools and answers with live data.

Code

GitHub: https://github.com/NishikantaRay/InsightTrack

NishikantaRay / InsightTrack

Self-hosted, privacy-first web analytics — the open-source alternative to Google Analytics

📊 InsightsTrack

Self-hosted, privacy-first web analytics — the open-source alternative to Google Analytics

Track visitors, pageviews, conversions, heatmaps, and Core Web Vitals — all on your own server. No cookies, no consent banners, no data selling. Deploy in under 15 minutes.

Live Demo · Quick Start · Features · Deploy · Docs

What is InsightsTrack?

InsightsTrack is a complete, production-grade web analytics platform you run yourself. It gives you the depth of Google Analytics 4 — real-time visitors, traffic sources, funnels, heatmaps, Web Vitals — without sending a single byte of your visitors' data to a third party.

Why teams choose it:

🔒 Privacy by design — no cookies, no fingerprinting, anonymous visitor IDs, GDPR-compliant, DNT/GPC honored.
⚡ Fast at any scale — a dual-database design (PostgreSQL for writes, DuckDB for reads) answers 90-day queries in under 100 ms even over millions of events.
🧩 Everything in one place —…

View on GitHub

The parts most relevant to this submission:

MCP tool registry — analytics-db/src/mcp/tools/registry.js (17 read-only tools)
MCP protocol handler (JSON-RPC 2.0, remote Streamable-HTTP transport) — analytics-db/src/mcp/protocol.js
The stdio bridge for local clients — mcp-server/src/index.js
The AI loop + BYO-key provider layer (Anthropic / OpenAI / Gemini) — analytics-db/src/routes/assistant.js and analytics-db/src/mcp/llm/provider.js

How I Built It

The dual-database core

InsightsTrack writes every tracking event to PostgreSQL and streams it into DuckDB, an embedded columnar engine. All analytics reads hit DuckDB — 90-day queries answer in tens of milliseconds, in-process, with no separate query cluster. Writes go to Postgres, reads come from DuckDB. That separation is what makes it fast and cheap to self-host.

Pulse: one tool registry, two front doors

The interesting decision was not building the AI assistant and the MCP integration as two separate things. There's one registry of 17 read-only tools (get_kpi, get_top_pages, get_funnel, get_realtime, list_sites, …). That single registry powers:

The in-dashboard Pulse panel — a streaming chat loop that lets an LLM call the tools and renders each result as a chart/table/KPI card.
MCP — the exact same tools, exposed to external clients.

Because both surfaces share the registry, an answer is consistent everywhere and I only maintain the tools once.

MCP: two transports

This is the connector heart of the project. I implemented both MCP transports:

Remote (Streamable-HTTP) — POST /api/mcp/http speaks JSON-RPC 2.0 (initialize / tools/list / tools/call). Clients that support remote MCP connect with just a URL + a bearer connect token. Nothing to install.
Local (stdio bridge) — a tiny mcp-server process (the only place the real @modelcontextprotocol/sdk is used) runs next to the client, speaks stdio, and proxies every call over HTTP to the API. It never touches the database — which keeps per-user site scoping and DuckDB's single-writer lock intact.

Connect tokens are scoped JWTs (scope: 'mcp', with jti so they can be revoked one-by-one), so a leaked token from one laptop can be killed without affecting others. All tools are read-only — the AI can query but can never change or delete data.

Bring-your-own-key, encrypted at rest

Pulse runs on your model key — Anthropic (Claude), OpenAI (GPT), or Google (Gemini). Keys are stored AES-256-GCM encrypted (dependency-free node:crypto, key derived from the server secret) and never leave your server. Precedence is BYO-key first, server key as fallback — so a self-hoster can either let every user bring their own, or set one server key so it "just works."

Result cards that do real work

Every tool returns a structured envelope — { summary, data, render, download, deepLink }. The dashboard turns that into a card with a CSV export, a view switcher (table ↔ bar ↔ line ↔ donut, client-side, no re-query), and a deep link to the matching dashboard page. Over MCP, the same envelope ships as structuredContent so agent clients get the data too.

The honest hard part

Getting Gemini to work over its OpenAI-compatible endpoint surfaced a subtle streaming bug: OpenAI streams tool-call arguments as fragments to concatenate, but Gemini sends the complete arguments object per delta (and sometimes repeats it) — naive concatenation produced invalid JSON like {}{} that Gemini then rejected on the next round. The fix: if an incoming fragment is already valid JSON, treat it as the whole value instead of appending. One provider quirk, but it's the difference between "Gemini works" and a mysterious INVALID_ARGUMENT.

Prize Categories

Best Use of Google AI — Pulse supports Google Gemini as a first-class model provider for the AI analyst. Bring a Gemini API key in Settings and every plain-English question about your analytics is answered by Gemini calling InsightsTrack's 17 read-only tools — in the dashboard and over MCP from Claude Desktop / Cursor.

Built with ❤️ as an open-source project. Try it, self-host it, or connect it to your favorite AI client. Feedback and stars welcome → https://github.com/NishikantaRay/InsightTrack

How I Finally Finished InsightTrack — My Abandoned Self-Hosted Analytics Platform

Nishikanta Ray — Sun, 24 May 2026 04:04:23 +0000

This is a submission for the GitHub Finish-Up-A-Thon Challenge

Project Details


Name	InsightTrack
GitHub	github.com/nishikantaray/insighttrack
Stack	React 18 · Vite 5 · Tailwind CSS · Express 4 · Node.js 20 · PostgreSQL · DuckDB

Demo

What I Built

InsightTrack is a self-hosted, privacy-first web analytics platform — my personal answer to the question "Why do I have to send all my users' data to Google just to know how many people visited my site?"

It tracks pageviews, sessions, conversions, user flows, and engagement — all on your own infrastructure, with no cookies and no third-party data sharing. The architecture uses PostgreSQL for all writes and DuckDB as an embedded columnar OLAP engine for analytics reads, achieving 10-100× the query speed of a traditional row-store setup.

I started InsightTrack during a long weekend when I was frustrated with the privacy implications of Google Analytics and the price tags on alternatives like Plausible and Fathom. The idea was simple: build a clean, self-hostable dashboard that you could drop a <script> tag into and be live in 5 minutes.

I got a working v1 out. It had a dashboard, auth, an onboarding wizard, basic charts, funnels, and a Docker Compose file that actually ran. Then I stopped. The project sat in a local folder for months — almost good enough, but not quite. The DuckDB sync was fragile. There was no dark mode on half the pages. Dozens of planned features were never built. Query performance fell apart past 30 days of data.

The bones were good. I just never gave it the finish it deserved.

How it works

Your Website
  └── analytics.js (tracking script, ~2 KB)
        │  POST /api/track/event
        ▼
  Express API (Node.js)
        │  Writes
        ▼
  PostgreSQL ──── Incremental sync worker (every 5 min)
                        │
                        ▼
                    DuckDB (OLAP reads)
                        │
                        ▼
  React Dashboard ◀─── GET /api/analytics/*

Write path: The tracking script sends events via navigator.sendBeacon. Express validates and inserts into PostgreSQL. Response is immediate — DuckDB is never in the write path.
Sync path: A high-watermark worker copies new rows from PostgreSQL → DuckDB incrementally, never rebuilding from scratch.
Read path: All 17 analytics endpoints read exclusively from DuckDB, running columnar aggregations 10-100× faster than a row-store query.
Auth: JWT-based authentication. All analytics routes are protected. Only /api/track/* and /api/auth/* are public.

PostgreSQL schema (source of truth)

Table	Purpose
`events`	Raw event log — pageviews, clicks, custom events
`sessions`	Session metadata — duration, page count, entry/exit pages
`sites`	Registered websites and their tracking keys
`funnels`	Funnel definitions with ordered steps
`daily_stats`	Pre-aggregated daily rollups
`users`	Dashboard user accounts

Demo

Landing Page

Hero

Features Grid

How It Works

Tech Stack

Comparison Table vs Google Analytics

Footer & CTA

Full landing page ![Full Landing Page](https://raw.githubusercontent.com/nishikantaray/insighttrack/main/screenshots/01-landing-full.png)

Authentication & Onboarding

Login	Register

Dashboard

Light Mode	Dark Mode

KPI Cards + Sparklines	Traffic Charts

Analytics Pages

User Flow (Sankey)	Real-Time

Funnels	Settings

Top Pages	Profile

Documentation	API Reference

Sidebar	Dark Landing

Stack: React 18 + Vite 5 + Tailwind CSS 3 · Express 4 + Node.js 20 · PostgreSQL + DuckDB · Docker Compose

The Comeback Story

Where it was (v1)

v1 had the core loop working: embed a tracking script → events land in PostgreSQL → a sync worker copies rows into a flat DuckDB table → the React dashboard reads from DuckDB. The fundamental architecture was sound.

What v1 shipped:

Dashboard with 4 KPI cards (Visitors, Pageviews, Bounce Rate, Avg. Session)
Traffic and pageview time-series charts (7d / 30d / 90d presets)
Top pages table
Basic conversion funnels
Device and country breakdown
JWT authentication, register/login, onboarding wizard with tracking snippet
Docker Compose deployment

But it had serious rough edges.

Performance wall. The DuckDB sync layer used a single flat table. On 90+ days of data, a KPI query scanned every row — ~620 ms on a local M1 machine. There was no partitioning, no archival strategy, and a crash meant rebuilding the entire table from scratch.

Half-finished features. There was a long list of planned but never-built ideas: UTM campaign tracking, comparison mode on charts, user flow analysis, a live visitor map on the Realtime page, engagement tracking, goal tracking, audience analytics, export to CSV/JSON — all unshipped.

UX gaps. The Settings page was a single form. The Documentation page was a placeholder. Half the pages lacked dark mode. There was no contextual help anywhere — a new user landing on the Funnels page had no idea what they were looking at.

No marketing story. The project had no landing page, no comparison table, no "why this instead of Google Analytics" pitch. It existed but didn't explain itself.

What changed (v1 → v2)

1. Hot+Cold Analytics Architecture

This was the most technically significant change. I replaced the flat DuckDB sync with a two-tier data lake:

Hot tier — DuckDB in-memory tables holding the last 30 days of events and sessions
Cold tier — Hive-partitioned Parquet files on disk for historical data, organized by site_id and event_date

data-lake/events/
  site_id=abc/
    event_date=2026-01-01/
      part-0001.parquet
    event_date=2026-01-02/
      part-0001.parquet

A transparent UNION ALL view sits on top of both tiers, so every existing dashboard query kept working without modification:

CREATE OR REPLACE VIEW events AS
  SELECT * FROM events_hot
  UNION ALL
  SELECT * FROM read_parquet(
    'data-lake/events/site_id=*/event_date=*/part-0001.parquet',
    hive_partitioning = true
  );

A dual-watermark incremental sync worker runs every 5 minutes, fetching only new rows from PostgreSQL using high-water marks (last_event_id for events, last_synced timestamp for sessions), then routing them to the correct tier based on age.

Result: 90-day queries dropped from ~620 ms → ~25 ms. A 25× speedup.

Recovery after a crash now resumes from the watermark instead of rebuilding the entire table.

2. Tracking Script — what it captures automatically

The auto-generated analytics.js (~2 KB) handles everything without configuration:

Data Point	How
Page URL & path	`window.location.href`
Referrer	`document.referrer`
Browser, OS, device	`navigator.userAgent` + screen width heuristics
Country	Timezone via `Intl.DateTimeFormat`
Session	Auto UUID in `sessionStorage`
Anonymous user ID	Random UUID in `localStorage` — no cookies
Outbound link clicks	`click` event listener
Scroll depth	25/50/75/100% milestones on page unload
Time on page	Seconds per page sent on unload
Heatmap clicks	x/y coordinates + CSS selector of every click
Rage clicks	3+ rapid clicks on same element within 1 second
Core Web Vitals	LCP, FID, CLS, INP, TTFB via `PerformanceObserver`
JS errors	`window.onerror` + `unhandledrejection` capture
Site search	Form submit interception
UTM parameters	`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
SPA navigation	`popstate` + `pushState` / `replaceState` listeners

Privacy built-in: DNT (navigator.doNotTrack) and GPC (navigator.globalPrivacyControl) are respected — if either is set, no data is collected.

Custom events are available via window.analytics.track('event_name', { ...properties }).

3. Complete v2 feature set

Core Dashboard

The main dashboard now has comparison mode — every chart can overlay the current period against the previous period. All 4 KPI cards have sparkline mini-charts. Date picker supports custom ranges in addition to presets.

Real-Time

Active visitor count (users in last 5 minutes, with pulsing indicator)
Interactive world map pinpointing active visitors by country
Live event stream — feed of the last 50–100 events as they happen
Active pages ranked by current visitor count
Real-time device breakdown

Engagement Analytics

Four metrics measured automatically by the tracking script:

Metric	What it shows
Scroll Depth	Per-page average scroll %; milestone table (25/50/75/100%)
Click Heatmaps	x/y dot map per page, top clicked elements ranked
Rage Click Detection	Pages and elements triggering 3+ rapid clicks within 1 second
Time on Page	Average, median, min/max read time per page

User Flow & Funnels

Sankey diagram showing entry pages → transitions → exit pages with proportional path thickness
Multi-step funnel builder (e.g., Landing → Signup → Checkout → Purchase) with per-stage drop-off and conversion rate
Saved funnel definitions

Conversion & Goals

Goal types: Pageview (URL match), Event (custom event), Duration (time on page), Scroll Depth (threshold)
A/B test tracking — create experiments, assign variants, compare conversion rates
Revenue attribution — attach dollar values to purchase events, see total revenue and average order value by traffic source

Audience Analytics

New vs. returning visitors — pie/donut chart + daily trend
Cohort analysis — heatmap grid of Day 1 / Day 7 / Day 30 retention by first-visit week
Visitor segments — filter by device, browser, OS, country and compare KPIs side by side

Content Analytics

Entry pages — top landing pages ranked by visitor count and entry rate
Exit pages — top departure pages ranked by exit count and exit rate
Page flow — where visitors go after each page
Site search — queries captured from form submit interception with frequency counts

Acquisition Analytics

Full UTM campaign dashboard — source, medium, campaign, term, content breakdowns with visitor counts, bounce rates, and session duration
Social media tab — automatic classification of Facebook, Twitter/X, LinkedIn, Instagram, YouTube, Reddit, Pinterest, TikTok traffic
Search keyword tracking — organic and paid keywords driving traffic
UTM link builder — generate tagged URLs directly in the dashboard

Performance Monitoring

Core Web Vitals collected automatically:

Metric	Good	Needs Improvement	Poor
LCP (Largest Contentful Paint)	≤ 2.5s	≤ 4.0s	> 4.0s
FID (First Input Delay)	≤ 100ms	≤ 300ms	> 300ms
CLS (Cumulative Layout Shift)	≤ 0.1	≤ 0.25	> 0.25
INP (Interaction to Next Paint)	≤ 200ms	≤ 500ms	> 500ms
TTFB (Time to First Byte)	≤ 800ms	≤ 1800ms	> 1800ms

Color-coded metric cards (green/yellow/red) + per-page breakdown table.

JavaScript error tracking: message, source file, line/column, stack trace, error trend chart over time.

Reporting & Export

Data export — JSON/CSV download for KPI, traffic, pages, sources data; PNG export for charts
Annotations — pin notes to specific dates on charts (e.g., "launched new homepage") with category badges (deployment/marketing/incident)
Scheduled reports — configure daily/weekly/monthly email delivery with recipient list
Custom dashboards — save personalized widget layouts

Multi-Site Management

Add and manage unlimited websites under one account
Per-site tracking snippets with one-click copy
Per-site data retention policies (30/90/180/365 days)
Automated cleanup of expired events and sessions

4. UX and documentation overhaul

Settings page rebuilt as a 4-tab layout: General, Notifications/Alerts, Site Manager, and Privacy
All 13 analytics pages gained a collapsible PageNote banner with a business explanation and a developer tip per page
InfoTooltip on every MetricCard and ChartCard
Documentation page rebuilt with dual-audience tabs (Business Owner / Developer) and an interactive 4-view architecture diagram
Dark mode enforced consistently across every page and component

5. Marketing landing page

Hero, features grid, 3-step "How It Works", tech stack cards, and a side-by-side comparison table vs. Google Analytics across 9 dimensions.

Before vs. After

Dimension	v1 (Before)	v2 (After)
90-day query time	~620 ms	~25 ms (25×)
DuckDB architecture	Single flat table, full scan	Hot (in-memory) + Cold (Parquet), UNION view
Sync on crash	Full table rebuild	Resumes from dual watermark
Analytics pages	7	13
Tracking data points	8	19
Real-Time page	Active count only	Map + event stream + device breakdown
Engagement tracking	None	Scroll depth, heatmaps, rage clicks, time on page
Conversion & Goals	Funnels only	Goals, A/B testing, revenue attribution
Audience analytics	None	New/returning, cohorts, segments
Content analytics	Top pages only	Entry/exit pages, page flow, site search
Acquisition analytics	None	UTM campaigns, social, keywords, link builder
Performance monitoring	None	Core Web Vitals + JS error tracking
Reporting	None	Export, annotations, scheduled reports, custom dashboards
Multi-site	Single site	Unlimited sites with per-site settings
Comparison mode	None	Previous-period overlay on all charts
Export	None	CSV / JSON / PNG
Settings page	Single form	4-tab layout with site manager
Contextual help	None	`PageNote` + `InfoTooltip` on every page
Dark mode coverage	Partial	Complete
Marketing landing page	None	Full page with comparison table

My Experience with GitHub Copilot

I'll be direct: I would not have shipped v2 without GitHub Copilot. Not because the individual problems were too hard — but because there were so many of them, and I was coming back to code I hadn't touched in months.

The architecture lift. The Hot+Cold DuckDB design required a new sync worker, new schema migrations, new UNION views, and updates to every existing query file simultaneously. Copilot helped me work through design decisions conversationally — I'd describe the constraint ("crash recovery must resume from a watermark, not rebuild the whole table") and it would walk me through the dual-watermark pattern, flag edge cases I hadn't considered (what happens to a row that ages from hot to cold between two sync cycles?), and generate the implementation that fit the existing codebase style.

The feature sweep. Going from 8 tracked data points to 19, from 7 pages to 13, from basic funnels to engagement tracking, cohort analysis, Web Vitals, and revenue attribution is a context-switching marathon. Copilot compressed the ramp-up time on each feature dramatically. When I opened the Acquisition page for the first time in months, Copilot immediately understood the existing data model, knew which UTM fields were already being captured in the tracking script, and scaffolded the campaign dashboard components that matched the existing useAnalytics hook pattern — not generic code, but code that fit this project.

The consistency work. The PageNote and InfoTooltip additions touched 13 pages. Adding Core Web Vitals collection to the tracking script required coordinating between analytics.js, the Express ingest route, the DuckDB schema, and the React performance page — four files that had to stay in sync. Copilot held the full context across all of them.

The documentation. Writing accurate technical docs for a system you know deeply is surprisingly tedious. Copilot drafted the architecture document for the hot/cold system from the actual code — referencing the real SQL, the real file paths, the real config variables — and I edited for clarity rather than writing from scratch.

The interaction style that worked best wasn't "write this for me." It was: here's the constraint, here's the existing pattern, here's where I'm confused. Copilot as a collaborator who has read your entire codebase is a genuinely different experience from Copilot as autocomplete. The finish-up phase of a project — juggling context across a dozen half-done things — is exactly where that kind of always-available, always-context-aware pair programmer pays off most.

InsightTrack v2 is the project I always meant to ship. It just needed time, a clear plan, and a better way to work through the backlog.

InsightTrack is open source — self-host your own privacy-first analytics in minutes.

SwiftCut: AI-Powered Video Silence Remover Built with GitHub Copilot CLI

Nishikanta Ray — Mon, 26 Jan 2026 16:46:06 +0000

This is a submission for the GitHub Copilot CLI Challenge

What I Built

SwiftCut is a local-first desktop application that automates the "Rough Cut" phase of video editing. It uses AI-powered audio analysis to instantly detect and remove silent segments from videos — no cloud uploads, no subscriptions, complete privacy.

The Problem I Solved

As a content creator, I spent hours manually cutting out silent pauses from my podcast recordings, tutorial videos, and vlogs. The workflow was:

Import video into heavy editing software
Scrub through timeline looking for silence
Manually mark and delete each silent segment
Repeat 50+ times per video 😩

SwiftCut automates this entire process in seconds.

Key Features

🎯 Smart Silence Detection — FFmpeg-powered audio analysis with configurable thresholds

⚡ Instant Results — Process a 10-minute video in under 5 seconds

🔒 100% Local & Private — Your videos never leave your machine

🎚️ Content Presets — Optimized settings for Podcasts, Tutorials, Vlogs, and Interviews

🤖 AI Natural Language Commands — Tell it what to do: "Remove all silences" or "Make a 30-second clip"

🎬 Reel Cutter — Split long videos into Instagram Reels, TikTok, or YouTube Shorts

🎙️ Voice Commands — Speak your edits using Web Speech API

↩️ Full Undo/Redo — Never lose your work

Tech Stack

Layer	Technology
Framework	Tauri v2 (Rust + WebView)
Frontend	React 19 + TypeScript
Styling	Tailwind CSS v4
State	Zustand
Video Processing	FFmpeg
AI	Multi-provider (Local, Ollama, OpenAI, Copilot SDK)

Demo

🎥 Video Walkthrough

▶️ Watch SwiftCut in Action

Screenshots

Landing Page — Clean, focused interface

Silence Detection — Visual timeline with detected segments

AI Commands — Natural language video editing

Reel Cutter — Split videos for social media

Try It Yourself

# Clone the repo
git clone https://github.com/yourusername/swiftcut.git
cd swiftcut

# Install dependencies
npm install

# Run in development
npm run tauri dev

# Build for production
npm run tauri:build

Requirements: Node.js 22+, Rust 1.93+, FFmpeg

My Experience with GitHub Copilot CLI

How Copilot CLI Transformed My Development

Building SwiftCut would have taken weeks without GitHub Copilot CLI. Here's how I used it:

1. FFmpeg Command Generation

FFmpeg has notoriously complex syntax. Instead of Googling for hours, I asked Copilot:

gh copilot suggest "ffmpeg command to detect silence below -30dB lasting more than 0.5 seconds"

Result:

ffmpeg -i input.mp4 -af "silencedetect=noise=-30dB:d=0.5" -f null -

This became the core of my silence detection algorithm.

2. Rust Backend Development

I'm primarily a TypeScript developer. Writing Rust for Tauri was daunting, but Copilot CLI helped:

gh copilot explain "how to parse FFmpeg stderr output in Rust and extract timestamps"

It gave me a complete regex pattern and parsing logic that I adapted for my lib.rs.

3. Complex Filter Chains

Building the export filter was tricky. I needed to keep non-silent segments and remove gaps:

gh copilot suggest "ffmpeg select filter to keep multiple time ranges and close gaps"

Result:

-vf "select='between(t,0,5)+between(t,8,20)',setpts=N/FRAME_RATE/TB"
-af "aselect='between(t,0,5)+between(t,8,20)',asetpts=N/SR/TB"

4. AI Planner System Prompt

I used Copilot to help design the system prompt for my AI planner:

gh copilot suggest "system prompt for an AI that converts natural language to FFmpeg commands"

This helped me structure the SWIFTCUT_SYSTEM_PROMPT that powers the natural language interface.

5. Cross-Platform Build Configuration

Setting up GitHub Actions for multi-platform builds:

gh copilot suggest "github actions workflow to build tauri app for mac windows and linux"

Got a working CI/CD pipeline in minutes instead of hours.

Impact on Development Experience

Metric	Without Copilot CLI	With Copilot CLI
FFmpeg learning curve	2-3 days	2 hours
Rust backend	1 week	2 days
Total development time	~3 weeks	~5 days
Stack Overflow visits	100+	~10

The "Aha!" Moment

The breakthrough came when I realized I could use Copilot CLI as a planning agent within the app itself. The system prompt I developed with Copilot's help now powers SwiftCut's AI command interface:

User: "Remove all silences longer than 1 second"
     ↓
AI Planner (Copilot-inspired prompt)
     ↓
FFmpeg: select='between(t,0,5)+between(t,8,20)...'
     ↓
Exported video with silences removed!

What I'd Tell Other Developers

Don't just ask for code — Ask Copilot CLI to explain concepts first
Use suggest for commands — Especially for complex CLI tools like FFmpeg, Docker, Git
Iterate with explain — If the first suggestion isn't perfect, ask it to explain and refine
Build your own prompts — The system prompts Copilot uses are great templates for your AI features

Technical Deep Dive

How Silence Detection Works

ORIGINAL VIDEO (10 minutes)
▓▓▓▓▓░░░▓▓▓▓▓▓▓░░▓▓▓▓░░░░▓▓▓▓▓▓▓▓░░▓▓▓▓▓▓░░░▓▓▓▓▓
     ▲       ▲       ▲           ▲         ▲
  silence silence silence    silence   silence

                    ↓ FFmpeg silencedetect

EXPORTED VIDEO (7 minutes)  
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
(All silence removed — 30% shorter!)

AI Provider Architecture

SwiftCut supports multiple AI backends:

type AIProvider = 'local' | 'copilot' | 'ollama' | 'openai';

// Switch providers in settings
setAIProvider({ 
  provider: 'ollama', 
  baseUrl: 'http://localhost:11434', 
  modelName: 'llama3.2' 
});

Provider	Use Case
Local	Offline, rule-based processing
Ollama	Privacy-focused local LLM
OpenAI	Most capable, requires API key
Copilot SDK	Coming soon!

What's Next

[ ] Waveform visualization in timeline
[ ] Transcript-based editing ("Find where I say 'demo'")
[ ] Batch processing multiple videos
[ ] Plugin system for custom filters
[ ] Mobile companion app

Acknowledgments

Built with ❤️ using:

Tauri — Amazing desktop framework
FFmpeg — The backbone of video processing
GitHub Copilot CLI — My AI pair programmer

What editing task takes you the longest? Let me know in the comments — maybe SwiftCut can help!

From Static to Smart: Designing an AI-First Developer Portfolio with Renderer, Gemini & MCP 🚀🚀

Nishikanta Ray — Thu, 22 Jan 2026 18:16:15 +0000

Transforming portfolio creation with Google Gemini AI and Model Context Protocol

https://www.youtube.com/watch?v=Txzplqg6oJo

🚀 Executive Summary

Renderer is an innovative portfolio framework that leverages Google Gemini to revolutionize how developers create and manage their online presence. By combining a configuration-first architecture with AI assistance through Model Context Protocol (MCP), users can generate, validate, and customize complete portfolios using natural language.

Key Innovation

Instead of wrestling with complex frameworks, users simply describe what they want, and Gemini handles the technical complexity—generating configurations, validating code, and providing instant guidance.

Live Links

🌐 Live Portfolio: https://nishikanta.in
📚 Documentation: https://renderer.nishikanta.in/docs
💻 Framework: https://github.com/NishikantaRay/renderer
🤖 MCP Server: https://github.com/NishikantaRay/renderer-mcp-server

🎯 Problem & Solution

The Problem

Developers face critical pain points when building portfolios:

⚠️ Framework Overload - Complex React/Vue setups with heavy build processes
⏰ Time Investment - Hours configuring, styling, and maintaining
🔒 Limited Flexibility - Templates that don't adapt to individual needs
📚 Documentation Fatigue - Searching through endless docs for simple changes

Our Solution

A static, configuration-driven framework enhanced by Google Gemini AI that:

✅ Generates complete portfolio configurations from natural language
✅ Validates TOML files and catches errors instantly
✅ Provides contextual documentation and examples
✅ Reduces setup time from hours to minutes

🧠 Google Gemini Integration

Dual-Layer AI Architecture

1. Gemini AI Studio (Ideation & Content Creation)

Used during initial development for:

📝 Outlining portfolio structure and sections
✍️ Drafting About, Resume, and project descriptions
🎨 Suggesting design patterns and layouts
🔄 Converting raw notes into polished copy

Why Gemini: Its advanced reasoning capabilities helped transform technical achievements into compelling narratives.

2. Gemini CLI (Development Workflow)

Terminal-native AI for rapid development:

# Generate configuration files
gemini "Create a resume.toml with experience and education sections"

# Content refinement
gemini "Rewrite this Markdown to be more technical and concise"

# Validation
gemini "Check this TOML file for schema errors"

# Documentation
gemini "Explain how to add dark mode to my portfolio"

Advantage: Seamlessly integrates with Git-based workflows and plain-text files.

3. Model Context Protocol (MCP) Server (AI Assistant)

Our breakthrough innovation—a persistent AI assistant that understands Renderer's architecture:

MCP Server Capabilities:

🔍 Semantic Documentation Search - Find answers in natural language
✅ Real-time TOML Validation - Catch errors before deployment
🎨 Template Generation - Create complete configs from user input
💡 Smart Examples - Context-aware code snippets
🗂️ Repository Navigation - Browse and understand file structure

🏗️ Technical Architecture

Core System

Renderer Framework
├── Configuration Layer (TOML)      # Human & AI readable
├── Content Layer (Markdown)        # Plain text documents
├── Presentation Layer (HTML/CSS/JS) # Vanilla web tech
└── AI Layer (Gemini + MCP)        # Intelligent assistance

Why This Stack Works

Configuration-Driven Design:

TOML files are both human and AI readable
No framework abstractions—pure data
Version control friendly
Deterministic output

Static-First Approach:

Zero build process
Instant deployment
Maximum performance
No server dependencies

AI-Assistable Architecture:

Every file is structured and parseable
Clear separation of concerns
Predictable patterns for AI reasoning

🤖 MCP Server Deep Dive

Architecture

Renderer MCP Server
├── GitHub Integration          # Access to framework repository
├── Documentation Engine        # Semantic search across docs
├── TOML Validator             # Schema validation
├── Template Generator         # Config creation
├── Example Provider           # Contextual snippets
└── Feature Search             # Capability discovery

Available Tools

explore_renderer_docs
- Natural language documentation queries
- Returns relevant sections with examples
validate_toml_config
- Schema validation
- Syntax checking
- Improvement suggestions
generate_starter_template
- Complete project scaffolding
- Customized to user needs
- Ready-to-deploy configurations
get_config_example
- Annotated configuration samples
- Context-aware suggestions
- Best practices included
search_renderer_features
- Feature discovery
- Implementation guides
- Integration examples

Setup & Usage

# Install globally
npm install -g renderer-mcp-server

# Use with Gemini CLI for AI assistance
gemini "Generate a portfolio configuration for John Doe with projects, resume, and blog"

# Or integrate with any MCP-compatible client
# The MCP server works with Google AI Studio API and Gemini models

💡 Real-World Use Cases

Use Case 1: Rapid Portfolio Generation

User: "I need a portfolio showcasing 5 projects, my resume, and a contact form"

Gemini + MCP Response:

Generates complete projects.toml with 5 project templates
Creates resume.toml with standard sections
Configures contact.html with form validation
Provides deployment instructions
Time saved: 2-3 hours → 10 minutes

Use Case 2: Configuration Validation

User: Uploads existing home.toml file

MCP Server:

✅ Validates syntax
⚠️ Identifies missing required fields
💡 Suggests improvements
📚 Links to relevant documentation

Use Case 3: Feature Discovery

User: "How do I add analytics dashboard to my projects page?"

Gemini Response:

[analytics]
enabled = true
title = "Project Analytics"

[analytics.charts]
weekly_activity = true
project_distribution = true

Plus step-by-step integration guide.

📊 Impact & Results

Quantifiable Improvements

Metric	Before	After	Improvement
Setup Time	4-6 hours	15-20 minutes	85% reduction
Configuration Errors	Common	Prevented	~90% reduction
Documentation Search	10-15 minutes	Instant	Near-instant
Portfolio Updates	30-45 minutes	5 minutes	83% faster

User Benefits

🚀 Developers: Focus on content, not configuration
🎨 Designers: Easy customization without code
📚 Students: Professional portfolios in minutes
💼 Professionals: Maintain portfolios effortlessly

🌟 Key Features

Portfolio Capabilities

🔧 Fully Configurable - Every aspect controlled via TOML
📄 Multi-Page Support - Home, Projects, Blog, Resume, Contact, Docs
🌙 Dark/Light Theme - Automatic detection + manual toggle
📱 Responsive Design - Mobile-first approach
⚡ Performance - Static files, instant loading
♿ Accessibility - Built-in ARIA support
🔍 SEO Optimized - Semantic HTML, proper meta tags

AI-Enhanced Workflows

💬 Natural Language Setup - Describe, don't configure
✅ Instant Validation - Real-time error checking
📝 Auto-Generation - Complete configs from prompts
🎯 Context-Aware Help - Relevant examples always
🔄 Iterative Refinement - Easy modifications

🎓 Technical Implementation

Configuration Example

# home.toml - Fully AI-generatable
[hero]
name = "Nishikanta Ray"
title = "Full-Stack Developer"
intro = [
    "Building developer-first tools and AI-assisted workflows",
    "Specialized in static-first architectures and minimal frameworks"
]

[hero.actions]
primary_text = "View Projects"
primary_link = "projects.html"
secondary_text = "Contact Me"
secondary_link = "contact.html"

[sections]
enabled_sections = ["projects", "skills", "experience"]

[theme]
mode = "auto"  # auto, light, or dark
accent_color = "#3b82f6"

MCP Tool Usage

// User prompt: "Create a blog config for tech writing"

// MCP generates:
{
  blog: {
    title: "Tech Blog",
    description: "Insights on web development",
    author: "Your Name"
  },
  settings: {
    posts_per_page: 6,
    enable_comments: true,
    enable_search: true,
    enable_categories: true
  },
  posts: [
    {
      id: "starter-post",
      title: "Welcome to My Blog",
      date: "2026-01-22",
      tags: ["introduction"]
    }
  ]
}

🚀 Getting Started

Option 1: AI-Assisted Setup (Recommended)

# 1. Install MCP Server
npm install -g renderer-mcp-server

# 2. Use Gemini CLI for AI assistance:
gemini "Create a portfolio configuration for [Your Name] with projects and resume"

# 3. Deploy to any static host
# Netlify, Vercel, GitHub Pages, Cloudflare Pages

Option 2: Manual Setup

# Clone repository
git clone https://github.com/NishikantaRay/renderer.git

# Serve locally
python -m http.server 8000
# or
npx serve .

# Configure via TOML files in config/
# Edit content in Markdown files

📚 Resources

Documentation

Repositories

Quick Start Commands

# Try the MCP server
npm install -g renderer-mcp-server

# Clone and run locally
git clone https://github.com/NishikantaRay/renderer.git
cd renderer && npx serve .

# Generate portfolio with Gemini CLI
gemini "Create a complete portfolio configuration for me"

👤 About the Creator

Nishikanta Ray - Full-Stack Developer specializing in:

🛠️ Developer experience and productivity tools
🤖 AI-assisted workflows and automation
🏗️ Minimal-framework, static-first architectures
📚 Open source contributions

Connect:

🌐 Portfolio: https://nishikanta.in
💻 GitHub: https://github.com/NishikantaRay

🎉 Conclusion

Renderer demonstrates the transformative potential of Google Gemini when applied to real-world developer workflows. By combining static-first architecture with intelligent AI assistance through MCP, we've created a system that:

This project proves that AI isn't just for chatbots—it's a fundamental tool for reimagining how we build and maintain software.

Built with Google Gemini | Powered by MCP | Made for Developers

Start building your AI-assisted portfolio today at renderer.nishikanta.in 🚀

Production-Grade Prompting with the Anthropic API

Nishikanta Ray — Sat, 17 Jan 2026 16:36:23 +0000

Concepts, Parameters, Streaming, Caching, and a Real Enterprise Example

Prompting in Anthropic (Claude) is not just about writing good instructions.

In production systems, prompts behave more like specifications than conversations.

This article explains how prompting actually works in Anthropic, how to design reliable and compliant prompts, and how to use JavaScript to build real systems—ending with a production-grade sentiment analysis prompt.

1. How Anthropic Prompting Really Works

Anthropic uses a message-based API.

Each request contains the entire conversation state.

Claude does not remember anything between API calls.

Mental model

You → send full conversation
Claude → continues from that context

Every request must include:

Who the assistant is
What rules apply
What the user just said
Any images or documents

2. Messages and Roles (Core Concept)

Anthropic uses three roles:

Role	Purpose
`system`	Hard rules, behavior, constraints
`user`	Input data or tasks
`assistant`	Previous model replies (conversation priming)

Example

messages: [
  { role: "user", content: "Hello! Only speak Spanish." },
  { role: "assistant", content: "Hola!" },
  { role: "user", content: "How are you?" }
]

Claude will answer in Spanish because:

Conversation history establishes the rule
Claude prioritizes consistency

Production rule

Put non-negotiable rules in system, not in conversation history.

3. System vs User Instructions (Why It Matters)

Instruction Type	Reliability
System	Strong, persistent
User	Soft, overrideable
Assistant	Priming only

Production-safe example

system: "You must respond only in Spanish."

This survives:

Long conversations
Truncated history
User attempts to override

4. Temperature: Controlling Randomness

Temperature controls how predictable Claude’s word choices are.

It does not control intelligence.

Temperature	Behavior	Use case
0.0–0.2	Deterministic	JSON, analytics
0.3–0.5	Controlled	Summaries
0.6–0.8	Creative	Writing
0.9+	Unstable	Rarely useful

Example

temperature: 0.0

Use this when:

Output must be parsed
Compliance matters
Decisions depend on correctness

5. stop_sequences: When the Model Must Stop

stop_sequences tells Claude when to stop generating.

stop_sequences: ["\nUser:"]

Claude stops immediately when it reaches that string.

Common uses

Prevent role leakage
End JSON cleanly
Stop agent loops

Key rule

Stop sequences are guards, not fixes for bad prompts.

6. Streaming Responses (Real-Time Output)

Streaming lets Claude send text incrementally.

with client.messages.stream(...) as stream:
  for text in stream.text_stream:
    print(text)

Why streaming exists

Faster perceived response
Better UX
Long outputs

When NOT to stream

JSON APIs
Tool calls
Strict schema validation

Production pattern

let buffer = "";

for (const chunk of stream.text_stream) {
  buffer += chunk;
  process.stdout.write(chunk);
}

// buffer now contains the full response

7. Multimodal Prompting (Images + Text)

Anthropic allows image + text together.

{
  role: "user",
  content: [
    { type: "image", source: {...} },
    { type: "text", text: "Count the containers." }
  ]
}

Rules

content must be an array
Image first, instruction second
Images only in user role

8. Prompt Caching and `cache_control`

Anthropic optimizes performance by caching repeated prompt prefixes.

This is good for:

System prompts
Templates
Policies

But dangerous for:

User data
Transcripts
Images
PII

9. `cache_control: { type: "ephemeral" }`

"cache_control": { "type": "ephemeral" }

This means:

Use this content once. Do not cache. Do not reuse. Do not persist.

When to use it

Data	Ephemeral
User input	✅
Call transcripts	✅
Images	✅
Customer feedback	✅

Why it matters

Prevents data reuse
Improves compliance posture
Reduces audit risk

10. JavaScript Example: Safe Prompt with Ephemeral Data

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20240620",
  max_tokens: 200,
  temperature: 0.0,
  system: "You are a deterministic analysis engine.",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "The service was slow and frustrating.",
          cache_control: { type: "ephemeral" }
        }
      ]
    }
  ]
});

console.log(response.content[0].text);

11. What Makes a Prompt Production-Grade

A production prompt has:

Clear role definition
Explicit constraints
Defined output format
Fail-closed behavior
Low temperature
No exposed reasoning
Safe handling of sensitive data

Good prompts are specifications, not conversations.

12. Production-Grade Sentiment Analysis Prompt

This prompt follows all best practices discussed above.

Prompt

Analyze the sentiment of the following customer message.

Rules:
- Classify sentiment as POSITIVE, NEGATIVE, or NEUTRAL
- Do not include personal data
- Do not infer intent beyond the text
- Limit text fields to 100 characters

Output:
Return ONLY valid JSON.
No explanations.

Schema:
{
  "sentiment": "POSITIVE | NEGATIVE | NEUTRAL",
  "confidence": 0.0-1.0,
  "summary": "string"
}

If sentiment cannot be determined, return:
{
  "sentiment": "NEUTRAL",
  "confidence": 0.0,
  "summary": "Insufficient data"
}

13. Sentiment Analysis: Full JavaScript Example

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20240620",
  max_tokens: 150,
  temperature: 0.0,
  system: "You are a strict sentiment classification engine.",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Support was slow and unhelpful.",
          cache_control: { type: "ephemeral" }
        }
      ]
    }
  ]
});

console.log(response.content[0].text);

14. Final Takeaway

Anthropic prompting works best when you treat prompts like contracts: explicit, constrained, deterministic, and safe.

DEV Community: Nishikanta Ray

What If Your Coding Agent Could Remember What It Learned Yesterday?

The problem: Your AI knows more than your codebase

Another example: Documentation versus reality

Meet Attic: A memory shelf for your coding agent

The library analogy that makes Attic click

The .attic/ folder is the library

INDEX.md is the catalogue card

Why not just put everything in the system prompt?

Keep the index small

Retrieve the details when needed

The four commands: Put knowledge in, get knowledge out

1. stash — save what you learned

2. recall — find what you already know

3. index — inspect the catalogue

4. pin, prune, and archive — manage the shelf

The part I find most interesting: The index is not the memory

Storage

Injection

What happens when you use /compact?

The browser extension: Knowledge doesn't only happen in your terminal

Browser to project memory

What is a clip?

Why reuse the CLI writer instead of building a second memory system?

The subtle distinction: Edit is not stash

Stash

Edit

Why appending everything is a problem

Why there is no delete endpoint

The browser companion is also a security boundary

Loopback: Keep communication local

Token authentication

Root allowlist: Where can it write?

Credential scanning: Don't stash secrets

The local-first philosophy

But should you commit .attic/ to Git?

A complete example: From bug investigation to reusable knowledge

Step 1: Start a new investigation

Step 2: The agent finds the root cause

Step 3: Save the discovery

Step 4: Start a new session

Step 5: Update the knowledge after the fix

What Attic does not try to do

The bigger idea: Agents need a knowledge lifecycle

Why browser memory is a natural next step

Getting started

Final thoughts

Try Attic

Tags

ai #claudecode #codex #opensource #developer-tools #codingagents #artificialintelligence #productivity

AI Skills Are Not Just Prompts: A Practical Architecture for Building, Evaluating, Shipping, and Maintaining Agent Skills

1. The Skill Lifecycle

2. Chapter 00 — How Skills Load and Run

Context Is a Resource

Design A — Everything in one file

Design B — Layered knowledge

3. Chapter 01 — Fit and Scope

Skill

Rule

Agent

Hook

Script

4. The Boundary Is More Important Than the Skill

5. Chapter 02 — Typing and Triggers

Activation Is a Classification Problem

False Positives and False Negatives

False positive

False negative

6. Chapter 03 — Shape and Architecture

Route

Pipeline

Loop

Map

Combining Shapes

7. Chapter 04 — Anatomy

SKILL.md Is the Hub

Hub-and-Spoke Architecture

Data vs Instructions vs Code

Instructions

Data

The `.attic/` folder is the library

`INDEX.md` is the catalogue card

1. `stash` — save what you learned

2. `recall` — find what you already know

3. `index` — inspect the catalogue

4. `pin`, `prune`, and `archive` — manage the shelf

What happens when you use `/compact`?

But should you commit `.attic/` to Git?

`SKILL.md` Is the Hub