initially the thought of this was pretty stressful, but being a good solutionist i proceeded with dicecting the issues one by one and presistent on finding a solition for them all.

The first thing is prioritizing platoforms, The stats were clear hence shared them with my manager, got iOS, Android prioritized in order and parked Windows for later as usage is extremly low. now the priority is set to the next thing.

The problem was not the workload. it was the cognitive overhead. i can barely understand my own code after a few months. here i am inheriting code from 6-7 people who clearly took shortcuts to ship fast. folder structure was a dump. files everywhere. and on top of reverse-engineering three codebases i had to track what is done, what is next, what is blocked: simultaneously, across all platforms this task alone without AI would be a real pain and would def take more than few months.

I opted to the $20 Claude subscription. so every session i was wasting the first chunk of context re-explaining the same codebase to Claude, re-orienting it to where i left off, re-answering questions it should already know. by lunch i was running out of tokens i had to use my colleague’s accounts to do whole thing again (Thanks Arun!)

out of this mess i needed a single place. one terminal. one browser tab. one AI session that already knows everything and picks up exactly where we left off, an interface for me and claude to read/update/learn about the project im working and it has to be highly structured, organized and prioritized.

so i built one. i call it the Command Center. if you have any other name to suggest, my inbox is open. this post is the full breakdown of what it is, how it works, and how you can shape it for your your own structure if you ever are in that spot, a little future pridction i think by the end of 2026 we all might have to work in this kind of set-up working on multiple projects simultaniously or atleast we will be capabble of that level of productivity.

What is this AI-Command Center

the idea is simple. instead of having our docs, tasks, changelogs in multiple apps and your terminal tabs scattered across screens for different platforms wokfing with different stages of the tasks or even totally different task altogether: and your daily runner claude-code has no means to know about all these instead you put a single shared operational layer above all your repos. not inside them. above them hence the term command center.

MyWorkspace/
├── ios/               ← own git repo, untouched
├── ios-dataKit/       ← own git repo, untouched
├── android/           ← own git repo, untouched
├── win/               ← own git repo, untouched
└── .ops/              ← Command Center (its own git repo)
    ├── docs/          ← documentation per project
    ├── todo/          ← task files per project + daily focus
    ├── memo/          ← decisions, KT notes, research
    ├── diagrams/      ← architecture diagrams + companion notes
    ├── changelog/     ← per-project ship history
    ├── scripts/       ← automation scripts
    └── dashboard/     ← local web dashboard

Don’t worry the project folders stay completely independent. git -C ios/ status never bleeds into git -C android/ status. you can add or remove a project folder without touching anything else, this is very important sepearation for corporate repositories where the restrictions are tight.

almost everything in .ops/ is a markdown, here is where it might looks like the WiKi pattern shared by the Andrej Karpathy. it is readable by me and the AI, diffs cleanly, and has zero dependencies you can stop here is you want a bare simple command-center but if you are like me this is not enough and there are many flaws here like doc’s going stale as we make changes so lets get to the text stage.

The scripts are the real MVP

As i said earlier i still use the 20$ subscription so for me tokens are really valuable running out of limit means one less productive day that might gift me a day of guilt so making use of scripts to save some routine commands that im sure will be helpful for claude to not be too dependent on remote calls, it might be confusting so here is example:

when i ask Claude “what is the git status across all my repos?” Claude tries to figure it out by calling tools one at a time burning tokens on reasoning and multiple tool calls to give me accurate and proper response

but if you have a script that does it:

# .ops/scripts/git_status_all.sh
for dir in android ios ios-dataKit ios-textEditor win; do
    branch=$(git -C "$ROOT/$dir" branch --show-current 2>/dev/null)
    changes=$(git -C "$ROOT/$dir" status --porcelain | wc -l | tr -d ' ')
    if [ "$changes" -gt 0 ]; then
        echo "● $dir — $branch ($changes uncommitted)"
    else
        echo "● $dir — $branch (clean)"
    fi
done

Claude runs the script. gets the answer in one shot. no reasoning, no guessing, no tool call loop you don’t have to write this manually you can just ask it to do, just make sure you get the code though.

the scripts i have accumulated up over time:

the pattern is always same: take something that would require Claude to do many tool calls or make assumptions, turn it into one script, let Claude just run it and read the output. you get a more reliable answer and you spend a fraction of the tokens.

the session_context.sh one is worth explaining. it runs as a session-start hook and injects the project context automatically before i type anything:

=== SESSION BRIEFING (2026-04-26) ===

REPOS
  ios          dev_eganathan   clean
  android      dev_eganathan   clean
  ios-dataKit  dev_eganathan   14 uncommitted  ← needs attention

HIGH PRIORITY (ios)
  - sessionId hardcoded as "" (TIBConverseInteractor.swift:83)
  - Localization migration uncommitted

LAST SESSION: 2026-04-22 — ios folder restructure, Settings flatten done
DOC SYNC: 8 stale docs — run /sync
=====================================

this replaces re-explaining the codebase every session. the entire briefing is generated from actual file state and costs about 100 tokens to inject i shared only a small portion of this but it basically added more relavant contexts that im sure will help claude so compare that to the 500–1000 tokens you’d spend manually orienting Claude each time.

Documentation that doesn’t go stale

the biggest problem with docs is they go stale the moment you stop actively maintaining them. and the honest truth is most people stop maintaining them pretty quickly.

so instead of relying on discipline, i wired it into the workflow. every doc has frontmatter that declares what code it describes:

---
project: ios
watches: ios/Features/Inbox/**, ios/Core/Network/**
lastVerified: a3f9c12
verifiedDate: 2026-04-20
---

watches is a glob pattern over source paths. lastVerified is the git commit hash when i last checked this doc.

doc_sync.js runs at session start: diffs lastVerified against HEAD per project, filtered by watches. if watched files changed, the doc is flagged stale. you get a list of exactly which docs need attention — not all of them, just the ones where the underlying code actually changed.

the workflow: read the diff, update the doc if needed, run --mark-current to stamp it with the new HEAD. stale docs are a session-start action item, not a quarterly effort.

one more thing worth building: a doc_sync_prompt.md template. when doc_sync.js flags a doc as stale, you need to give Claude a consistent prompt for reviewing it. the template fills in {{DOC_PATH}}, {{GIT_DIFF_STAT}}, {{CHANGED_FILES}}, and {{DOC_CONTENT}} — Claude reads the diff, decides what changed, updates only what is wrong or outdated, and preserves the frontmatter format. without a template you end up writing a different prompt every time and the quality of the review varies. one template file in scripts/, referenced whenever /sync runs.

Task management across platforms

one file per platform. ios_todos.md, android_todos.md, win_todos.md. same structure in all of them:

## High Priority
- [ ] Fix session ID bug in TIBConverseInteractor.swift:83

## Medium Priority
- [ ] Add unit test target

## Low Priority
- [ ] Refactor legacy auth flow

## Completed
- [x] 2026-04-20 — Migrated Localizable strings

there is also daily.md — today’s focus, separate from the long-running backlogs. daily_reset.sh resets it each morning, carries over anything incomplete from yesterday, and pulls the top items from each project’s High Priority section so you are never starting from blank. at end of day you move done items back to the project file and carry over the rest.

it is not rocket science but it works because everything is in one place and Claude can read all of it directly — no context switching, no “go check Linear”, no copy-pasting.

Memos, KT notes, and changelogs

these three are the most underrated parts of the system. they get skipped when people think about “what does an AI need to know” but they are exactly what the AI is missing when it gives you advice that misses context.

Memos (memo/) are for anything that does not fit in a doc or a todo. decision logs, architecture choices, research, migration plans, meeting outputs. the key thing about a memo is it captures the why. a doc says “the auth middleware works like this”. a memo says “we rewrote the auth middleware because legal flagged the session token storage in April”. without the memo Claude treats every piece of code as a deliberate, still-valid decision. with the memo it knows what is intentional and what is technical debt inherited from a compliance scramble.

KT notes (memo/kt/<platform>/YYYY-MM-DD_topic.md) are specifically for inheriting a codebase. when someone does a knowledge transfer session, you write it up here. when you figure out something non-obvious about how the code works, you write it up here. these are the things that would take a new person weeks to discover by reading code — undocumented conventions, “we don’t touch that file because”, quirks of the build system, context behind a weird architectural choice. writing them down once means Claude knows them forever.

Changelogs (changelog/<project>.md) are append-only per-project ship logs:

| 2026-04-15 | Migrated inbox to VIPER          | PR #441 |
| 2026-04-08 | Upgraded to AGP 8.3              | PR #438 |
| 2026-03-22 | Added push notification handling | PR #421 |

one row per notable change. the practical use: “did we ship X on all platforms yet?” — you check the changelog instead of grepping git history across five repos. also useful at standup when someone asks what shipped last week.

The local web dashboard

the dashboard is a local Node.js server. no framework, no build step, runs offline, starts in two seconds.

node .ops/dashboard/server.js
# opens at localhost:3000

File browser — tree sidebar over all docs, todos, memos. files render as Markdown. todo files have live checkboxes — clicking one calls POST /api/toggle and writes the change directly to disk.

Git status panel — polls all repos in parallel. branch, last commit, time ago, dirty file count.

Full-text search — index built at startup from every .md, .txt, .sh file. AND-matched with scoring. returns results with line-number snippets. useful when you remember something exists but can not remember which doc it is in.

Doc staleness indicators — green/yellow/red dots next to each doc in the sidebar based on doc_sync.js output. a resync button re-runs the script and refreshes the cache.

Task creation — a form on every page to add a todo at any priority level to any project. finds the right heading and inserts the item, updates the Last updated: stamp.

Shape it to your problems — the CMD tabs and RSS feeds

here is the thing: everyone’s pain is different. the folder structure and scripts above are the common base. but the reason this actually works day-to-day is that you can add whatever else you actually need on top.

for me, the two things i added that made the biggest difference:

CMD view — xterm.js + node-pty over WebSocket. a real terminal embedded in the browser, one tab per project. each tab opens a PTY session in that project’s directory. per-project quick-command buttons — you configure a label and a shell command, they appear as buttons above the terminal. so Build Debug runs ./gradlew assembleDebug in the Android tab. Sync Pods runs pod install in the iOS tab. i click once, watch it run. no switching windows, no remembering the exact command flags.

before this i was constantly switching terminal windows and losing track of which one was which. now everything is in one browser tab.

RSS feeds / newsletters — each platform has its own dev newsletter and release channel. iOS dev forum, Android releases, Kotlin blog. i added an RSS tab. feed URLs live in a feeds.json file, keyed by platform:

{
  "ios": [
    { "label": "iOS Dev Weekly", "url": "https://iosdevweekly.com/issues.rss" },
    { "label": "Swift Blog", "url": "https://swift.org/atom.xml" }
  ],
  "android": [
    { "label": "Android Developers Blog", "url": "https://feeds.feedburner.com/blogspot/hsDu" }
  ]
}

the server fetches them server-side (handles redirects, CDATA stripping), renders as cards per platform. i stop by when i want to catch up. no separate app, no subscriptions, no algorithm deciding what i see — just the feeds i actually want, inside the same tab i already have open.

neither of these exist in anyone else’s command center because they are solving my specific workflow pain. the point is the base layer gives you the foundation. the top layer is yours to build.

other ideas i have seen or thought about that i haven’t built yet: a meeting notes tab that auto-stamps today’s date, a platform-specific analytics panel, a PR review queue for when you work with a team.

The two-tier AI model

the local web dashboard has a built-in AI chat powered by Mistral 7B via Ollama — not Claude. this is the layer that routes cheap questions away from the cloud.

the RAG pipeline:

question
   │
   ▼
embed ──► LanceDB vector search ──► top-k doc chunks
                                          │
                                          ▼
                             Mistral 7B ◄── context + question
                                          │
                                          ▼
                                    streamed answer
                               (with source file citations)

at startup the server walks all docs, chunks them, embeds them and stores the index in LanceDB. conversation history (last 12 turns) is passed with each request. topics can be filtered per platform.

but here is the part that matters more — the local model is also wired directly into Claude as an MCP tool. not just the dashboard chat, but Claude itself can call it:

search_docs(query, project?)  — semantic search over the LanceDB index
ask_local(question, project?) — full RAG query to Mistral 7B

so when you ask Claude “where is the WebSocket manager?” Claude does not think about it, does not run three tool calls, does not burn tokens. it calls ask_local, gets the answer back from the local model as a tool response, and continues. the routing decision is encoded in CLAUDE.md as explicit rules so it happens automatically:

You
 │
 ├── Complex reasoning ──────────────────► Claude (API tokens)
 │    debugging, architecture,
 │    multi-file refactoring, codegen
 │
 └── Lookups + summaries ──► local MCP ──► Mistral 7B (free, local)
      "where is X?", todos,
      file summaries, templates

questions that go local: “where is ClassName defined”, “what files are in folder X”, “summarise this file”, “what todos are open for Android”, “what is the VIPER template for a new scene”, anything answerable by reading the existing docs.

questions that use Claude: multi-file refactoring, debugging across call chains, cross-platform analysis with real reasoning, writing new features.

in practice around 60–70% of session queries route to the local model. those run free on my machine. Claude gets the work that actually needs it.

Tracking what you saved

there is one more hook worth adding: a PostToolUse hook on the local MCP calls. every time Claude calls ask_local or search_docs, a small Python script logs the call to a token_savings.jsonl file with a timestamp, the tool used, and an estimated token count saved:

{"ts": "2026-04-26T10:32:11", "tool": "ask_local",    "estTokensSaved": 400}
{"ts": "2026-04-26T10:33:45", "tool": "search_docs",  "estTokensSaved": 250}

the same hook also outputs a reminder back into Claude’s context: “you just used the local model — append [tib-mcp-info] to the sentence in your response that came from this result.”

that [tib-mcp-info] tag in the response is how you know which parts Claude answered from local knowledge vs the local model. it is easy to skip but worth keeping — after a few weeks you can look at the JSONL and get a rough sense of how many tokens the routing saved. it also keeps you honest about whether the local model is actually being used or whether Claude is quietly doing everything itself.

The session cache — picking up exactly where you left off

the session briefing knows “what was worked on last session” because /callitaday writes a session_summary.json at the end of each day. the structure:

{
  "date": "2026-04-22",
  "platform": "ios",
  "done": [
    "Settings flatten complete — SettingsSUI/NewUI/Settings_base merged into Features/Settings",
    "Helpers restructured — Contacts moved to Features/Contacts"
  ],
  "carriedOver": [
    "Android: edge to edge mandate for Play Store — not checked yet"
  ],
  "decisions": [
    "Contacts gets Features/Contacts/ not buried in Helpers",
    "URLSchemeAnalyser lives in Core/DeepLinker/"
  ],
  "openQuestions": [
    "CustomContextMenu still needs to move to Features/Inbox/Actions/"
  ],
  "keyFiles": [
    "native/TeamInbox.xcodeproj/project.pbxproj",
    "native/TeamInbox/Features/Settings/"
  ]
}

next morning, session_context.sh reads this file and includes the done, carriedOver, decisions, and openQuestions fields in the briefing. Claude starts the session knowing exactly where things were left — no re-reading git log, no “what were we working on?”. the keyFiles field is useful if you want Claude to immediately orient to the relevant parts of the code.

/callitaday is the slash command that writes this. it wraps the session: moves done items from daily.md back to the project todo files, carries over incomplete items, writes the JSON. it is the last thing you run before closing the terminal.

Setting this up yourself

the minimum version of this is five files and an afternoon:

1. create a parent workspace folder above all your repos
2. add a .ops/ folder with docs/, todo/, memo/, scripts/
3. write a CLAUDE.md at the workspace root — folder layout, git command prefixes, working conventions, routing rules
4. write session_context.sh or a simple briefing script that runs git -C <project>/ status across all repos and prints a summary — hook it to session start
5. write one doc per project covering the folder structure and architecture, add the watches frontmatter

that is the base. that alone kills the “re-explain everything every session” problem and the “docs live in Notion somewhere” problem.

layer on top in order of payoff:

• daily_reset.sh and the daily.md workflow — probably adds the most to day-to-day sanity
• doc_sync.js — if you are writing docs and want them to stay honest
• the dashboard — once you want a visual layer over all of it
• the CMD tabs — if you are constantly switching terminal windows for the same commands
• the local model + MCP — when token pressure is real and your doc library is large enough to justify a RAG pipeline

do not build all of it at once. start with the folder structure and the CLAUDE.md. add the rest as you actually feel the pain they solve.

What changed

before: open the right repo in Xcode, find the right Notion page, check Slack for where i left off, re-explain the codebase to Claude, watch the first 30% of my context window fill with boilerplate before writing a single line of actual code.

after: one terminal, one browser tab, one Claude session. the Command Center has the state of every repo, every doc, every task, every recent decision — and the cheap questions never reach the cloud.

the whole system is about 1,500 lines of Node.js, a handful of shell scripts, and Markdown files. no heavy dependencies, no cloud services, runs entirely offline.

if you are managing more than two active repos and you are constantly re-orienting your AI every session — this pattern is worth trying. you do not have to build the whole thing. start with the folder structure and a CLAUDE.md. that alone will change how your sessions feel.

the rest you will figure out as you go, shaped around whatever is actually slowing you down. that is the point.

a note on this post — the ideas, the frustration, the architecture, the decisions are all mine. i used Claude to help structure and articulate things i already knew but was too lazy to write out properly. felt right to mention it given the whole post is about working with AI. use your tools.

after writing this i came across andrej karpathy’s wiki pattern — same instinct around plain files, single source of truth, readable by humans and machines. worth looking up if this resonated.

before we go further i humbly request you to read this article, don’t stop reading it after the first few paragraph(Again, Thanks Aditya), keep reading till the end there are twists and turns so please try to read it and get back here on this reflection journey.

Recently, a colleague shared an article with me titled “You Don’t Have To” by Scott Smitelli. I highly recommend reading it. It really makes you think about how we might slowly be losing our edge due to the heavy use of Large Language Models (LLMs), like how i stoped memorizing phone numbers coz its available on my phone book except mine ;0 and find it hard to calculate in head with large numbers continuesly like the guy in typical village shop guy does quickly.

With ai there are so many techniques i still experiment with and i continiously work on. It’s great to use AI to brainstorm, validate, or debate your thoughts, but don’t let it run the show for you. If you do, you’ll slowly vanish into the background.

Reading this article—and later debating it with my manager—sent me down a rabbit hole of self-reflection. It sparked a deep, sometimes controversial, conversation between us. Is AI destroying the art of coding? Or is it simply the next step in our evolution? After stepping back to clear my thoughts, here are my reflections on where I stand with AI tools today.

The “Zero to One” Myth

There’s a romanticized idea in our industry that we are still building things “from zero.” The truth is, that hasn’t been true for years. We went from machine code, to assembly, to C, to Java, and Kotlin. Today, 95% of developers rely heavily on layers of abstractions like frameworks, APIs, and libraries that they didn’t build and often don’t fully understand under the hood.

AI isn’t some alien invasion; it is merely the newest layer of abstraction in this ongoing shift.

Also, AI isn’t a “magic button.” Unless you are simply cloning a well-documented repository, AI cannot build a full-fledged, custom solution from start to finish with a single prompt. Real engineering still needs architecture, logic, and deep orchestration—all of which must come from a human.

Value over “The Craft”

Many developers treat coding as an art form. They pride themselves on writing the perfect, zero-dependency code. But let’s be practical: in a professional setting, we aren’t here just to write poetry in code. We are here to solve problems, deliver value to our clients, and ultimately earn a living.

All I care about are the humans using the tools I build. The exact ingredients or the “purity” of the code doesn’t matter nearly as much as the end-user’s experience. Getting too caught up in digging through abstractions or coding like a purist feels unnecessary if it stands in the way of delivering a working, valuable product.

The Danger of “AI Slop”

That being said, my manager raised a very valid point: the sheer ease of generating content with AI easily leads to garbage. Generative AI can produce 10x more content in a single day than humans have produced in a lifetime. When people generate and publish content without any personal input, refinement, or real intent, we get what he accurately called “AI slop.”

I agree completely. Outputting anything publicly without real personal meaning—just creating for the sake of creating without adding value—is wrong. It pollutes the internet and human conversations. The tool is only as good as the intent behind it.

The Axe and the Chainsaw

Think of AI as an electric chainsaw, and traditional coding as an axe (an example from the article shared above).

Knowing how to use an axe remains extremely important even when a chainsaw is available. The chainsaw can break or fail. More importantly, a lumberjack who has cut down trees with an axe a thousand times knows exactly how to angle the cut so the tree falls right where he wants it to.

Using AI tools doesn’t turn your brain to mush, provided you actually understand the changes it makes to your creation. Let me be real here THIS IS EXTREMLU HARD! That’s actually why I’m thankful for Claude’s token limitations sometimes. It forces me to stay involved. AI shifts your role from pure execution to orchestration. You cannot outsource your JUDGEMENT, EXPERIENCE, or PERSONALITY. If you rely entirely on AI without applying these human traits, the quality of your work will drop, and you will eventually become redundant.

An Equalizer for Communication

Beyond just writing code, AI is an incredible equalizer for communication. Not everyone is a natural wordsmith. For those of us who are less vocal or struggle to find the right phrasing, AI is a tool that helps us communicate our technical intent clearly. It’s not about faking a voice; it’s about polishing it. It helps take the raw intent inside my head and words it rightly for the world to understand, let me say its not easy to get it the way we have in mind there are limitations like token limit, it tries to end it very quickly by saying the crux of things or to draggy but never, or almost never the right proprotion.

Wielding the Future

My philosophy in this rapidly changing landscape is simple:

• When we only had machine code, we coded in assembly.
• When we got high-level languages like Java and Kotlin, we used them.
• Now we have AI, and we should use it extensively.
• If AI becomes inaccessible or too expensive tomorrow, we simply go back to coding in Kotlin. We should be prepared for that.

To make sure I’m prepared, I’ve actually started “AI fasting.” As silly as it might sound, taking a break from AI helps me make sure I can still build or think differently without these tools. I’m not sure how every employer feels about this, but for me, spending three days coding without AI is a healthy practice. If feature demands increase, I might have to tweak this schedule, but I try not to be too rigid about it, so far looks like we are going all in this new era.

Recently, I was scrolling through Instagram and saw a reel where a developer made a great point. He said: “Before AI, you delivered a project in a week. Now, even with AI, it still takes a week—why is that?” His answer was that while AI generates code quickly, fixing the bugs or tweeking the code it creates and also reviewing it has become extremely harder.

That really stood out to me. I still have some lingering doubts about all of this, but what matters most is finding the right balance,keeping it away is not going to help me, im going to embrance it tight find its strenth and weekness and use it to my advantage.

I don’t wish to nitpick on philosophies people have, that have no real meaning to the end user. Coding like a “caveman” shouldn’t be a badge of honor. Utilizing tools like MCP, plugins, and advanced prompting is how we stay forward-thinking and effective in this day and age, especially in the phase we are moving in right now.

Ultimately, machines should take the drudgery out of life. AI brings that promise to our doorsteps. It’s up to us to embrace it, orchestrate it responsibly, and ensure that we are using it to add real value, rather than just contributing to the noise of confusions around.

I wrote this just to clear some thoughts in my head regarding the excesive ai tool usage, i myself fell into this trap of vibe working for a short period of time, i regret it coz i lost the chance to learn what happend in that part of the code, i thought skipping that was okey but that above article opens by eyes. This is also a phase of learning but don’t ever do that on work/personal projects that you truly care, thats a big no no, Blinde Vibecoding is okey for prototying some personal productivity tools, features and such silly thing never on any real product that you truely care.

Want to generate diagrams directly in Claude? Here is the fast track configuration for your claude_desktop_config.json:

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": [
        "-y",
        "@drawio/mcp"
      ]
    }
  }
}

Restart Claude Desktop, and then ask: “Create a flowchart for a user login system.”

Why Draw.io with Claude?

If you are like me, explaining architecture or complex flows in text can get wordy and confusing. “Component A talks to B, which then signals C…” is much harder to parse than a simple arrow connecting boxes.

The Official Draw.io MCP Server (@drawio/mcp) bridges this gap. It allows Claude to:

1. Generate Diagrams: Create flowcharts, sequence diagrams, and system architectures from scratch.
2. Edit Existing Diagrams: Update diagrams based on new requirements.
3. Render Visuals: See the diagram directly in the chat interface (depending on the client support).

This is a game-changer for documentation, brainstorming, and technical specs.

Prerequisites

Before we start, ensure you have the following:

• Claude Desktop App: Installed on your Mac or Linux machine.
• Node.js: Version 18 or higher.
  • Check your version: node -v
  • If missing, I recommend using nvm (Node Version Manager) to install it.

Step-by-Step Setup Guide

1. Locate Configuration File

You need to edit the highly specific claude_desktop_config.json file.

On macOS: Open your terminal and run:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

(Or use nano, vim, or open -e if you don’t use VS Code)

On Linux: The file is typically located at:

~/.config/Claude/claude_desktop_config.json

2. Add the Draw.io Server

Add the following entry to the mcpServers object in your config file. If the file is empty, wrap it in curly braces.

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": [
        "-y",
        "@drawio/mcp"
      ]
    }
  }
}

What is this doing?

• It tells Claude to run the npx command.
• The -y flag automatically creates the environment without prompting.
• @drawio/mcp is the official package containing the server logic.

3. Restart Claude

For the changes to take effect:

1. Close the Claude Desktop interface completely.
2. Re-open it.

You should see a generic “MCP” icon or indicator (depending on your version) showing that tools are loaded.

Alternative: Setup with Claude Code CLI

If you prefer using the Claude Code CLI (command line interface) instead of the Desktop app, you can add the server directly using the claude mcp add command.

This is particularly useful if you want to scope the tool to a specific project or your user account without editing JSON files manually.

One-Line Setup

Run this command in your terminal:

claude mcp add drawio --scope user -- npx -y @drawio/mcp

Breakdown of the command:

• claude mcp add drawio: Tells Claude to add a new MCP server named “drawio”.
• --scope user: Installs it globally for your user account (use --scope project to install for the current folder only).
• --: Separator indicating the start of the actual server command.
• npx -y @drawio/mcp: The command to run the Draw.io server.

Once added, you can verify it with:

claude mcp list

How to Use It

Once connected, you can converse with Claude naturally about diagrams.

Creating a New Diagram

Prompt:

“Create a sequence diagram for an OAuth 2.0 authentication flow involving a User, Client App, Authorization Server, and Resource Server.”

Claude will generate the XML or specific format required for Draw.io and often provide a link or a rendered view.

Editing a Diagram

If you have a diagram file (e.g., XML) in your project context, you can ask Claude to modify it.

Prompt:

“Update the attached architecture diagram to include a Redis cache layer between the API and the Database.”

Complex Visualizations

You aren’t limited to simple boxes. You can ask for:

• Mind Maps: “Create a mind map for a marketing strategy.”
• ER Diagrams: “Generate an Entity-Relationship diagram for an e-commerce database schema.”
• Network Topologies: “Draw a high-availability AWS network setup with public and private subnets.”

Troubleshooting

“Command not found: npx”

If Claude complains it can’t find npx, you might need to provide the absolute path.

1. Run which npx in your terminal. (e.g., /usr/local/bin/npx)
2. Update your config:

   "drawio": {
     "command": "/usr/local/bin/npx",
     "args": ["-y", "@drawio/mcp"]
   }
   

Server Error / Disconnection

If the server crashes, check your Node.js version. The Draw.io MCP server requires a modern Node environment. Ensure node -v returns v18.x.x or newer.

Resources

• Official Draw.io MCP GitHub Repository
• Model Context Protocol Documentation
• Draw.io Website

Voice input can dramatically improve UX, yet most apps don’t use it. Here’s why you should:

✅ Zero app size increase - Uses Android’s native speech recognition (no libraries!) ✅ No permissions required - Works out of the box ✅ 3-5x faster input - Users can speak 150+ words/min vs typing 40 words/min ✅ Better accessibility - Essential for users with motor impairments ✅ Reduces friction - One tap vs multiple keyboard interactions ✅ Professional polish - Shows attention to UX details

The catch? It requires network connectivity and device support. But with proper availability checks, you can gracefully hide the feature when unavailable—making it a pure win when present.

Why Most Apps Skip This Feature

Despite being a native Android capability since API 8, many developers overlook voice input because:

1. Assumed complexity - Developers think it requires heavy ML libraries
2. Unclear implementation - Documentation is scattered
3. Network dependency concerns - Fear of handling edge cases
4. Device fragmentation worries - Uncertainty about availability
5. “The keyboard already has it” - The most common misconception

The truth? It’s simpler than adding a date picker, and this guide shows you how to handle all edge cases properly.

“But Users Have Voice Input on Their Keyboard Already!”

This is the most common objection developers raise. Yes, most mobile keyboards (Gboard, SwiftKey, Samsung Keyboard) have a mic button. But here’s why in-app voice input is still essential:

The Reality of Keyboard Voice Input Usage

📊 Usage statistics show a problem:

• Most users don’t even know the keyboard mic button exists
• Many forget about it after the initial setup
• Some disable it accidentally during keyboard customization
• The keyboard mic is visually small and easy to miss
• Users must actively look for it among other keyboard buttons

Why In-App Voice Input is Superior

1. Discoverability

❌ Keyboard mic: Hidden among 30+ keyboard keys, looks like any other button
✅ In-app mic: Prominent, contextual, right next to the input field

Example: A text field with a mic icon in the trailing position is immediately obvious. The keyboard mic? Users have to open the keyboard, scan for it, and remember it exists.

2. Context-Aware UX

// In-app voice can be contextual
TextField(
    label = { Text("Product Review") },
    trailingIcon = { MicIcon() }  // Clear purpose: "Speak your review"
)

The keyboard mic has no context - it’s the same button whether you’re entering an email, a password, or a product review. In-app voice input can show field-specific prompts like “Describe your issue” or “Speak your address”.

3. User Intent and Flow

• Keyboard mic: Requires users to:

  1. Tap the input field
  2. Wait for keyboard to appear
  3. Look for the mic button among keyboard keys
  4. Tap the mic
  5. Speak

• In-app mic: Simplified flow:

  1. Tap the mic icon (no keyboard needed!)
  2. Speak

Result: 2 fewer steps and no keyboard lag.

4. Visual Prominence

5. Accessibility Considerations

Users with motor impairments or visual limitations benefit significantly:

• Larger, easier-to-tap target
• Better contrast and visibility
• Screen readers can announce it contextually
• Doesn’t require precise keyboard navigation

6. User Psychology

Explicit invitation > Hidden capability

When users see a mic icon next to a text field, it:

• Signals that voice input is encouraged
• Reduces friction - they don’t need to hunt for it
• Increases adoption - visible features get used more
• Feels intentional - the app wants them to use voice

The keyboard mic feels like a generic fallback. The in-app mic feels like a first-class feature.

Real-World Data Points

While specific metrics vary by app, general patterns show:

• 📈 5-10x higher voice input usage with prominent in-app mic icons
• 🎯 New user discovery - many users don’t realize keyboard voice exists
• ♿ Accessibility gains - significant usage increase among users with disabilities
• 📱 Mobile-first users especially benefit (small screen, fat fingers)

The Hybrid Approach: Best of Both Worlds

The ideal solution is not either/or, but both:

✅ In-app mic for discoverability and context ✅ Keyboard mic still works as a fallback

Users get:

• A prominent, obvious voice input option
• Fallback if they prefer keyboard mic
• Contextual prompts and better UX
• No downsides!

When “Just Use the Keyboard” Fails

Some scenarios where keyboard voice input is insufficient:

1. Custom keyboards - Not all keyboards have voice input
2. Enterprise devices - Some organizations disable keyboard voice for security
3. Locked-down keyboards - Educational or restricted environments
4. Non-Google keyboards - Third-party keyboards may lack voice features
5. Disabled by user - Some users disable keyboard permissions

Your in-app implementation works regardless of keyboard choice.

The Bottom Line

“Users have voice on their keyboard” is like saying:

• “Don’t add a search icon, users can use Ctrl+F”
• “Don’t add a share button, users can copy-paste”
• “Don’t add undo, users can manually fix mistakes”

Just because a capability exists somewhere doesn’t mean it’s discoverable or convenient.

In-app voice input is about removing friction and guiding users toward better UX. The fact that keyboard voice exists is great - your in-app implementation makes it more likely to actually be used.

Ever wanted to add voice input to your Android app with minimal effort? Speech-to-Text functionality can dramatically improve user experience, especially for note-taking, messaging, or search features.

In this guide, we’ll build a clean, reusable Speech-to-Text component using Jetpack Compose that wraps Android’s native speech recognition API.

🎯 What We’re Building

A composable speech recognition system with:

• ✅ Simple API - One composable function to handle everything
• ✅ Lifecycle-aware - Properly managed with Activity Result API
• ✅ Locale support - Respects app language settings
• ✅ Availability checking - Gracefully handles devices without speech recognition
• ✅ Reusable state - Clean separation of concerns

🏗️ Architecture Overview

Our implementation consists of three main components:

1. SystemSpeechToTextHelper - A utility object that handles Android’s RecognizerIntent
2. SpeechToTextState - A state holder that manages the speech recognition launcher
3. rememberSpeechToText() - A composable function that creates and remembers the state
4. SpeechToTextButton (Bonus) - A ready-to-use UI component

📝 Implementation

1️⃣ The Helper Object

First, let’s create a helper object to encapsulate all Android-specific speech recognition logic:

object SystemSpeechToTextHelper {
    fun getAppLocale(): Locale {
        return try {
            Locale.forLanguageTag(Language.currentLocale.value.code)
        } catch (e: Exception) {
            Locale.getDefault()
        }
    }

    fun createRecognitionIntent(
        languageModel: String = RecognizerIntent.LANGUAGE_MODEL_FREE_FORM,
        locale: Locale = getAppLocale(),
        prompt: String? = null,
        maxResults: Int = 1
    ): Intent {
        return Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH).apply {
            putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, languageModel)
            putExtra(RecognizerIntent.EXTRA_LANGUAGE, locale.toLanguageTag())
            putExtra(RecognizerIntent.EXTRA_MAX_RESULTS, maxResults)
            prompt?.let { putExtra(RecognizerIntent.EXTRA_PROMPT, it) }
        }
    }

    fun extractSpokenText(result: ActivityResult): String? {
        return if (result.resultCode == Activity.RESULT_OK) {
            result.data
                ?.getStringArrayListExtra(RecognizerIntent.EXTRA_RESULTS)
                ?.firstOrNull()
                ?.takeIf { it.isNotBlank() }
        } else {
            null
        }
    }

    fun isRecognitionAvailable(context: Context): Boolean {
        val pm = context.packageManager
        val activities = pm.queryIntentActivities(
            Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH),
            PackageManager.MATCH_DEFAULT_ONLY
        )
        return activities.isNotEmpty()
    }
}

Key Features:

• 🌍 Locale handling - Automatically uses your app’s current language
• 🎤 Flexible configuration - Customize prompt, language model, and result count
• ✅ Validation - Ensures speech recognition is available on the device
• 🧹 Clean extraction - Filters out blank results

2️⃣ The State Holder

Next, we create a state class that manages the speech recognition lifecycle:

@Stable
class SpeechToTextState(
    private val launcher: ManagedActivityResultLauncher<Intent, ActivityResult>,
    private val prompt: String?,
    val isAvailable: Boolean
) {
    fun launch(
        customPrompt: String? = prompt,
        customLocale: Locale? = null
    ) {
        val intent = SystemSpeechToTextHelper.createRecognitionIntent(
            prompt = customPrompt,
            locale = customLocale ?: SystemSpeechToTextHelper.getAppLocale()
        )
        launcher.launch(intent)
    }
}

Why @Stable? The @Stable annotation tells Compose that this class follows specific stability contracts, allowing for better recomposition optimizations.

3️⃣ The Composable Function

Now comes the magic - a composable that ties everything together:

@Composable
fun rememberSpeechToText(
    prompt: String? = null,
    onResult: (String) -> Unit
): SpeechToTextState {
    val context = LocalContext.current

    val launcher = rememberLauncherForActivityResult(
        contract = ActivityResultContracts.StartActivityForResult()
    ) { result ->
        SystemSpeechToTextHelper.extractSpokenText(result)?.let { spokenText ->
            onResult(spokenText)
        }
    }

    val isAvailable = remember {
        SystemSpeechToTextHelper.isRecognitionAvailable(context)
    }

    return remember(launcher, prompt, isAvailable) {
        SpeechToTextState(
            launcher = launcher,
            prompt = prompt,
            isAvailable = isAvailable
        )
    }
}

Key Points:

• 🔄 Activity Result API - Modern way to handle activity results
• 💾 Remembered state - Survives recompositions
• 🎯 Callback pattern - Clean result handling via lambda

4️⃣ Bonus: Ready-to-Use Button Component

For convenience, here’s a pre-built button component:

@Composable
fun SpeechToTextButton(
    speechToTextState: SpeechToTextState,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    iconSize: Dp = 24.dp,
    tint: Color = Color.Unspecified,
    contentDescription: String? = null
) {
    IconButton(
        onClick = speechToTextState::launch,
        enabled = enabled && speechToTextState.isAvailable,
        modifier = modifier
    ) {
        Icon(
            painter = painterResource(id = R.drawable.ic_mic),
            contentDescription = contentDescription,
            tint = tint,
            modifier = Modifier.size(iconSize)
        )
    }
}

🚀 Real-World Implementation Examples

Example 1: TextField with Voice Input (Production-Ready)

Here’s how to properly integrate voice input with a text field, including validation and network checking:

@Composable
fun SmartTextField(
    value: String,
    onValueChange: (String) -> Unit,
    modifier: Modifier = Modifier,
    label: String = "",
    placeholder: String = "",
    isError: Boolean = false,
    errorMessage: String? = null,
    maxLength: Int? = null,
    singleLine: Boolean = true
) {
    val context = LocalContext.current
    var showNetworkWarning by remember { mutableStateOf(false) }

    // Check network connectivity
    val isNetworkAvailable = remember {
        val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
        cm.activeNetwork != null
    }

    val speechToText = rememberSpeechToText(
        prompt = "Speak $label"
    ) { spokenText ->
        // Handle max length validation
        val newText = if (maxLength != null) {
            spokenText.take(maxLength)
        } else {
            spokenText
        }
        onValueChange(newText)
    }

    Column(modifier = modifier) {
        OutlinedTextField(
            value = value,
            onValueChange = { newValue ->
                // Enforce max length on manual input too
                val sanitized = if (maxLength != null) {
                    newValue.take(maxLength)
                } else {
                    newValue
                }
                onValueChange(sanitized)
            },
            label = { Text(label) },
            placeholder = { Text(placeholder) },
            isError = isError,
            singleLine = singleLine,
            modifier = Modifier.fillMaxWidth(),
            trailingIcon = {
                // Only show mic icon if speech recognition is available
                if (speechToText.isAvailable) {
                    IconButton(
                        onClick = {
                            if (isNetworkAvailable) {
                                speechToText.launch()
                            } else {
                                showNetworkWarning = true
                            }
                        }
                    ) {
                        Icon(
                            painter = painterResource(id = R.drawable.ic_mic),
                            contentDescription = "Voice input for $label",
                            tint = if (isNetworkAvailable) {
                                MaterialTheme.colorScheme.primary
                            } else {
                                MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)
                            }
                        )
                    }
                }
            },
            supportingText = {
                when {
                    errorMessage != null && isError -> {
                        Text(
                            text = errorMessage,
                            color = MaterialTheme.colorScheme.error
                        )
                    }
                    maxLength != null -> {
                        Text(
                            text = "${value.length}/$maxLength",
                            modifier = Modifier.fillMaxWidth(),
                            textAlign = TextAlign.End
                        )
                    }
                }
            }
        )

        // Network warning
        if (showNetworkWarning) {
            Text(
                text = "Voice input requires internet connection",
                color = MaterialTheme.colorScheme.error,
                style = MaterialTheme.typography.bodySmall,
                modifier = Modifier.padding(start = 16.dp, top = 4.dp)
            )
            LaunchedEffect(Unit) {
                delay(3000)
                showNetworkWarning = false
            }
        }
    }
}

Usage:

@Composable
fun FeedbackForm() {
    var userName by remember { mutableStateOf("") }
    var feedback by remember { mutableStateOf("") }
    val maxFeedbackLength = 500

    Column(modifier = Modifier.padding(16.dp)) {
        SmartTextField(
            value = userName,
            onValueChange = { userName = it },
            label = "Your Name",
            placeholder = "John Doe",
            maxLength = 50,
            singleLine = true
        )

        Spacer(modifier = Modifier.height(16.dp))

        SmartTextField(
            value = feedback,
            onValueChange = { feedback = it },
            label = "Feedback",
            placeholder = "Tell us what you think...",
            maxLength = maxFeedbackLength,
            singleLine = false
        )
    }
}

Example 2: Search Bar with Voice Input

@Composable
fun VoiceEnabledSearchBar(
    query: String,
    onQueryChange: (String) -> Unit,
    onSearch: () -> Unit,
    modifier: Modifier = Modifier
) {
    val speechToText = rememberSpeechToText(
        prompt = "What are you looking for?"
    ) { spokenText ->
        onQueryChange(spokenText)
        // Auto-search after voice input
        onSearch()
    }

    SearchBar(
        query = query,
        onQueryChange = onQueryChange,
        onSearch = { onSearch() },
        active = false,
        onActiveChange = {},
        modifier = modifier,
        leadingIcon = {
            Icon(
                imageVector = Icons.Default.Search,
                contentDescription = "Search"
            )
        },
        trailingIcon = {
            Row {
                // Clear button
                if (query.isNotEmpty()) {
                    IconButton(onClick = { onQueryChange("") }) {
                        Icon(
                            imageVector = Icons.Default.Close,
                            contentDescription = "Clear"
                        )
                    }
                }

                // Voice input button (only if available)
                if (speechToText.isAvailable) {
                    IconButton(onClick = { speechToText.launch() }) {
                        Icon(
                            painter = painterResource(id = R.drawable.ic_mic),
                            contentDescription = "Voice search"
                        )
                    }
                }
            }
        },
        placeholder = { Text("Search products...") }
    ) {
        // Search suggestions
    }
}

Example 3: Multi-line Text Input with Append Mode

Perfect for note-taking or messaging apps:

@Composable
fun VoiceNoteEditor() {
    var noteContent by remember { mutableStateOf("") }
    var isRecording by remember { mutableStateOf(false) }

    val speechToText = rememberSpeechToText(
        prompt = "Speak your note"
    ) { spokenText ->
        // Intelligently append or replace
        noteContent = when {
            noteContent.isEmpty() -> spokenText
            noteContent.endsWith(".") || noteContent.endsWith("!") || noteContent.endsWith("?") ->
                "$noteContent $spokenText"
            else ->
                "$noteContent. $spokenText"
        }
        isRecording = false
    }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp)
    ) {
        OutlinedTextField(
            value = noteContent,
            onValueChange = { noteContent = it },
            modifier = Modifier
                .fillMaxWidth()
                .weight(1f),
            placeholder = {
                Text("Start typing or tap the mic to speak...")
            },
            textStyle = MaterialTheme.typography.bodyLarge
        )

        Spacer(modifier = Modifier.height(16.dp))

        Row(
            modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.SpaceBetween,
            verticalAlignment = Alignment.CenterVertically
        ) {
            // Word count
            Text(
                text = "${noteContent.split("\\s+".toRegex()).size} words",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.onSurfaceVariant
            )

            // Voice input button
            if (speechToText.isAvailable) {
                FilledTonalButton(
                    onClick = {
                        isRecording = true
                        speechToText.launch()
                    }
                ) {
                    Icon(
                        painter = painterResource(id = R.drawable.ic_mic),
                        contentDescription = null,
                        modifier = Modifier.size(20.dp)
                    )
                    Spacer(modifier = Modifier.width(8.dp))
                    Text(if (isRecording) "Listening..." else "Add Voice Note")
                }
            }
        }
    }
}

Example 4: Form with Conditional Voice Input

Shows how to conditionally enable voice input based on field type:

@Composable
fun UserRegistrationForm() {
    var name by remember { mutableStateOf("") }
    var email by remember { mutableStateOf("") }
    var bio by remember { mutableStateOf("") }

    Column(modifier = Modifier.padding(16.dp)) {
        // Name field - voice input enabled
        SmartTextField(
            value = name,
            onValueChange = { name = it },
            label = "Full Name",
            maxLength = 50
        )

        Spacer(modifier = Modifier.height(16.dp))

        // Email field - voice input disabled (too error-prone)
        OutlinedTextField(
            value = email,
            onValueChange = { email = it },
            label = { Text("Email") },
            keyboardOptions = KeyboardOptions(
                keyboardType = KeyboardType.Email
            ),
            modifier = Modifier.fillMaxWidth()
            // No voice input for email - typing is more accurate
        )

        Spacer(modifier = Modifier.height(16.dp))

        // Bio field - voice input enabled
        SmartTextField(
            value = bio,
            onValueChange = { bio = it },
            label = "Bio",
            placeholder = "Tell us about yourself...",
            maxLength = 200,
            singleLine = false
        )
    }
}

⚠️ Critical Implementation Guidelines

1. Always Check Availability

Never show the mic icon if speech recognition is unavailable. This creates a poor UX when users tap it and nothing happens.

// ✅ GOOD - Only show when available
if (speechToText.isAvailable) {
    SpeechToTextButton(speechToTextState = speechToText)
}

// ❌ BAD - Shows disabled button (confusing UX)
SpeechToTextButton(
    speechToTextState = speechToText,
    enabled = speechToText.isAvailable  // Don't do this!
)

Why? On devices without Google services (some custom ROMs, enterprise devices), the feature won’t work. Hiding it entirely is cleaner than showing a permanently disabled button.

2. Handle Network Connectivity

Speech recognition requires active internet connection. Check before launching:

fun isNetworkAvailable(context: Context): Boolean {
    val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
    return cm.activeNetwork != null
}

// Usage
val isNetworkAvailable = remember {
    isNetworkAvailable(context)
}

IconButton(
    onClick = {
        if (isNetworkAvailable) {
            speechToText.launch()
        } else {
            // Show snackbar or toast
            Toast.makeText(context, "Voice input requires internet", Toast.LENGTH_SHORT).show()
        }
    }
) {
    Icon(
        painter = painterResource(id = R.drawable.ic_mic),
        tint = if (isNetworkAvailable) {
            MaterialTheme.colorScheme.primary
        } else {
            MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)
        }
    )
}

Best Practice: Show the mic icon in a dimmed state when offline, and display a brief message when tapped.

3. Input Validation After Voice Input

Always validate voice input just like you would keyboard input:

val speechToText = rememberSpeechToText { spokenText ->
    // Sanitize and validate
    val sanitized = spokenText
        .trim()
        .take(maxLength)
        .filter { it.isLetterOrDigit() || it.isWhitespace() }

    // Check if valid
    if (sanitized.isNotEmpty()) {
        inputValue = sanitized
    } else {
        showError("Invalid input received")
    }
}

Common validations:

• Length limits - Trim to max length
• Character filtering - Remove special chars if needed
• Empty checks - Handle blank results
• Format validation - Email, phone, etc.

4. Permissions - None Required!

Good news: No runtime permissions needed! Android’s speech recognition uses Google’s cloud service, which handles all the heavy lifting.

This is a huge advantage over custom speech recognition libraries that require RECORD_AUDIO permission.

5. Locale and Language Support

By default, the implementation respects your app’s current locale:

fun getAppLocale(): Locale {
    return try {
        Locale.forLanguageTag(Language.currentLocale.value.code)
    } catch (e: Exception) {
        Locale.getDefault()
    }
}

For multilingual apps, you can override the locale per-field:

// Spanish input for a specific field
speechToText.launch(customLocale = Locale("es", "ES"))

// French input
speechToText.launch(customLocale = Locale.FRANCE)

6. When NOT to Use Voice Input

Some fields are better suited for keyboard input:

❌ Email addresses - Punctuation and special characters are error-prone ❌ Passwords - Security risk + poor accuracy ❌ Credit card numbers - High error rate + security concerns ❌ URLs - Complex syntax not recognized well ❌ Code snippets - Special characters and formatting issues

✅ Good use cases: ✔ Names, addresses, descriptions ✔ Search queries ✔ Notes and messages ✔ Feedback and reviews ✔ Long-form text content

📊 UX Impact: The Numbers

Why voice input matters for your app’s user experience:

Real-world impact:

• 📝 A 100-word product review takes 2.5 minutes typing vs 40 seconds speaking
• 🔍 Voice search feels instantaneous vs typing lag
• ♿ Critical for users with motor impairments, RSI, or visual limitations
• 🌍 Easier for non-native keyboard users

✅ Why This Implementation is Superior

Compared to Keyboard Input:

✔ 3-5x faster input for long text ✔ Lower cognitive load - speaking is more natural than typing ✔ Better mobile experience - no tiny keyboard frustration ✔ Hands-free operation - can be used while multitasking

Compared to Third-Party Libraries:

✔ Zero app size increase - uses system APIs ✔ No permissions required - no RECORD_AUDIO prompt ✔ Always up-to-date - Google maintains the recognition engine ✔ No API keys or quotas - completely free ✔ Better privacy - uses Google’s standard speech service (same as Gboard)

Compared to Custom ML Models:

✔ No model training needed ✔ No storage for ML models (models can be 50MB+) ✔ Supports 100+ languages out of the box ✔ Continuously improving - benefits from Google’s updates

🎯 When Voice Input Makes Sense

Perfect Use Cases:

• 📝 Note-taking and memos - Natural dictation flow
• 💬 Messaging and chat - Quick voice-to-text messages
• 🔍 Search queries - Faster than typing
• 📋 Long-form content - Reviews, feedback, descriptions
• ♿ Accessibility features - Essential for many users
• 🚗 Hands-free scenarios - When typing isn’t safe

Skip Voice Input For:

• 🔒 Sensitive data - Passwords, PINs, SSNs
• 📧 Format-specific fields - Emails, URLs, credit cards
• 🔢 Numeric codes - OTPs, account numbers
• 💻 Technical input - Code, command-line syntax

🚀 Performance Considerations

App Size Impact: 0 KB - Uses system APIs only

Runtime Performance:

• Minimal memory usage
• Lazy initialization (only when needed)
• No background processes
• Network call only during active recognition

Battery Impact:

• Negligible - recognition happens on Google’s servers
• No continuous listening (only when user taps mic)
• Automatic cleanup after recognition

🎁 Quick Implementation Checklist

Before shipping voice input to production, verify:

• ✅ Mic icon only shows when isAvailable == true
• 🌐 Network connectivity is checked before launching
• ✍️ Input validation applied to voice results
• 📏 Max length limits enforced
• 🌍 Proper locale configuration
• ⚠️ User feedback for network errors
• 📱 Tested on devices without Google services
• ♿ Content descriptions added for accessibility
• 🎨 Visual feedback when mic is active (if custom UI)

🔗 Related Resources

• Android Speech Recognition Guide
• Jetpack Compose Activity Result API
• Material Design Voice Input Guidelines

💡 Final Thoughts

Voice input is a low-effort, high-impact feature that most apps overlook. With zero dependencies, no permissions, and minimal code, there’s little reason not to add it where appropriate.

The key differentiators:

1. Always check availability - hide the feature gracefully when unavailable
2. Validate network state - provide feedback when offline
3. Apply proper validation - treat voice input like any other input
4. Choose appropriate fields - not everything needs voice input

By following these guidelines, you’ll provide a professional, polished experience that sets your app apart.

That’s it! You now have a fully functional, production-ready speech-to-text component for Jetpack Compose. 🎉

Feel free to customize this implementation to fit your app’s specific needs. If you have questions or suggestions, reach out via my social handles! 😊

Happy coding! 🚀

Stop building custom camera UIs for document capture. ML Kit Document Scanner gives you a professional, AI-powered document scanning experience with just a few lines of code:

✅ Automatic edge detection - AI finds document boundaries instantly ✅ Perspective correction - Automatically straightens skewed documents ✅ Shadow removal - Intelligent lighting correction ✅ Multi-page support - Scan multiple pages in one session ✅ Quality enhancement - Auto-adjusts contrast and brightness ✅ Minimal code - 10 lines vs 500+ for custom implementation ✅ Small library size - ~3MB vs building from scratch

The result? Professional document scanning that rivals dedicated scanner apps, with 95% less code and effort.

Why Developers Still Use Basic Camera Capture

Despite ML Kit Document Scanner being available since 2022, most apps still use basic camera capture for documents. Here’s why:

1. Lack of awareness - Many developers don’t know it exists
2. “Camera is good enough” - Until users complain about quality
3. Custom UI preference - Wanting full control (unnecessary)
4. Assumed complexity - Thinking it requires ML expertise
5. Library size concerns - Actually very reasonable (~3MB)

The reality: Basic camera capture for documents creates terrible UX compared to proper document scanning.

The Problem with Basic Camera Capture

What Happens with Regular Camera:

// Typical camera implementation
val cameraIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
launcher.launch(cameraIntent)
// User gets: blurry, skewed, shadowy image

User experience issues:

• 📸 No guidance on document boundaries
• 🔲 Manual cropping required (tedious)
• 🌓 Poor lighting = unusable scans
• 📐 Perspective distortion (holding phone at angle)
• 📄 One page at a time (inefficient for multi-page docs)
• 🎨 No enhancement (washed out, low contrast)

Result: Users waste time cropping, retaking photos, and dealing with poor quality scans.

What ML Kit Document Scanner Provides

The Complete Package:

1. Real-time Edge Detection

   • AI instantly finds document corners
   • Visual overlay shows detected boundaries
   • Works even with complex backgrounds

2. Auto Perspective Correction

   • Straightens tilted/skewed documents
   • Removes keystoning (trapezoid effect)
   • Perfect rectangular output every time

3. Smart Enhancement

   • Removes shadows and glare
   • Adjusts contrast automatically
   • Optimizes for text readability
   • Handles various lighting conditions

4. Multi-page Scanning

   • Scan entire documents in one flow
   • Add/remove pages easily
   • Page reordering built-in

5. Multiple Export Formats

   • High-quality images (JPEG/PNG)
   • PDF generation built-in
   • Configurable resolution

Implementation

Step 1: Add Dependencies

Add to your app’s build.gradle:

dependencies {
    // ML Kit Document Scanner
    implementation 'com.google.android.gms:play-services-mlkit-document-scanner:16.0.0-beta1'
}

Library size: ~3MB (tiny compared to the functionality you get!)

Step 2: Configure Scanner Options

import com.google.mlkit.vision.documentscanner.GmsDocumentScanner
import com.google.mlkit.vision.documentscanner.GmsDocumentScannerOptions
import com.google.mlkit.vision.documentscanner.GmsDocumentScannerOptions.RESULT_FORMAT_JPEG
import com.google.mlkit.vision.documentscanner.GmsDocumentScannerOptions.RESULT_FORMAT_PDF
import com.google.mlkit.vision.documentscanner.GmsDocumentScannerOptions.SCANNER_MODE_FULL

// Create scanner with options
val options = GmsDocumentScannerOptions.Builder()
    .setGalleryImportAllowed(true)              // Allow importing from gallery
    .setPageLimit(10)                            // Max 10 pages per scan
    .setResultFormats(RESULT_FORMAT_JPEG, RESULT_FORMAT_PDF)  // Get both formats
    .setScannerMode(SCANNER_MODE_FULL)           // Full scanning experience
    .build()

val scanner = GmsDocumentScanning.getClient(options)

Scanner Modes:

• SCANNER_MODE_FULL - Complete UI with all features (recommended)
• SCANNER_MODE_BASE - Minimal UI, faster scanning

Step 3: Launch Scanner and Handle Results

// Activity Result Launcher
private val scannerLauncher = registerForActivityResult(
    ActivityResultContracts.StartIntentSenderForResult()
) { result ->
    if (result.resultCode == RESULT_OK) {
        val scanningResult = GmsDocumentScanningResult.fromActivityResultIntent(result.data)

        scanningResult?.let { scanResult ->
            // Get scanned pages
            scanResult.pages?.let { pages ->
                pages.forEach { page ->
                    // Access page image URI
                    val imageUri = page.imageUri

                    // Use the scanned image
                    loadScannedImage(imageUri)
                }
            }

            // Get PDF if generated
            scanResult.pdf?.let { pdf ->
                val pdfUri = pdf.uri
                val pageCount = pdf.pageCount

                // Save or share PDF
                savePdfDocument(pdfUri, pageCount)
            }
        }
    }
}

// Launch scanner
fun startDocumentScan() {
    scanner.getStartScanIntent(this)
        .addOnSuccessListener { intentSender ->
            scannerLauncher.launch(
                IntentSenderRequest.Builder(intentSender).build()
            )
        }
        .addOnFailureListener { exception ->
            // Handle error
            Log.e("Scanner", "Failed to start scanner", exception)
        }
}

Step 4: Complete Jetpack Compose Integration

Here’s a production-ready composable implementation:

@Composable
fun DocumentScannerButton(
    onDocumentsScanned: (List<Uri>) -> Unit,
    onPdfGenerated: (Uri, Int) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true
) {
    val context = LocalContext.current
    val activity = context as? ComponentActivity

    // Scanner options
    val scanner = remember {
        val options = GmsDocumentScannerOptions.Builder()
            .setGalleryImportAllowed(true)
            .setPageLimit(10)
            .setResultFormats(RESULT_FORMAT_JPEG, RESULT_FORMAT_PDF)
            .setScannerMode(SCANNER_MODE_FULL)
            .build()
        GmsDocumentScanning.getClient(options)
    }

    // Result launcher
    val scannerLauncher = rememberLauncherForActivityResult(
        contract = ActivityResultContracts.StartIntentSenderForResult()
    ) { result ->
        if (result.resultCode == ComponentActivity.RESULT_OK) {
            val scanResult = GmsDocumentScanningResult.fromActivityResultIntent(result.data)

            scanResult?.let {
                // Handle scanned images
                it.pages?.let { pages ->
                    val imageUris = pages.mapNotNull { page -> page.imageUri }
                    if (imageUris.isNotEmpty()) {
                        onDocumentsScanned(imageUris)
                    }
                }

                // Handle PDF
                it.pdf?.let { pdf ->
                    onPdfGenerated(pdf.uri, pdf.pageCount)
                }
            }
        }
    }

    // Launch scanner
    fun launchScanner() {
        activity?.let { act ->
            scanner.getStartScanIntent(act)
                .addOnSuccessListener { intentSender ->
                    scannerLauncher.launch(
                        IntentSenderRequest.Builder(intentSender).build()
                    )
                }
                .addOnFailureListener { exception ->
                    Log.e("DocumentScanner", "Failed to start", exception)
                }
        }
    }

    Button(
        onClick = { launchScanner() },
        enabled = enabled,
        modifier = modifier
    ) {
        Icon(
            imageVector = Icons.Default.DocumentScanner,
            contentDescription = null,
            modifier = Modifier.size(20.dp)
        )
        Spacer(modifier = Modifier.width(8.dp))
        Text("Scan Document")
    }
}

Usage:

@Composable
fun DocumentUploadScreen() {
    var scannedImages by remember { mutableStateOf<List<Uri>>(emptyList()) }
    var pdfUri by remember { mutableStateOf<Uri?>(null) }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp)
    ) {
        DocumentScannerButton(
            onDocumentsScanned = { images ->
                scannedImages = images
                Toast.makeText(
                    context,
                    "Scanned ${images.size} pages",
                    Toast.LENGTH_SHORT
                ).show()
            },
            onPdfGenerated = { uri, pageCount ->
                pdfUri = uri
                Toast.makeText(
                    context,
                    "PDF created with $pageCount pages",
                    Toast.LENGTH_SHORT
                ).show()
            }
        )

        // Display scanned images
        LazyColumn {
            items(scannedImages) { imageUri ->
                AsyncImage(
                    model = imageUri,
                    contentDescription = "Scanned page",
                    modifier = Modifier
                        .fillMaxWidth()
                        .height(200.dp)
                        .padding(vertical = 8.dp)
                )
            }
        }
    }
}

Real-World Use Cases

1. ID/Document Verification

Perfect for KYC (Know Your Customer) flows:

@Composable
fun KYCDocumentUpload() {
    var idCardUri by remember { mutableStateOf<Uri?>(null) }

    Column {
        Text("Upload ID Card", style = MaterialTheme.typography.titleLarge)

        DocumentScannerButton(
            onDocumentsScanned = { images ->
                idCardUri = images.firstOrNull()
                // Automatically extract text with ML Kit Text Recognition
                verifyIDDocument(idCardUri)
            },
            onPdfGenerated = { _, _ -> }
        )

        idCardUri?.let { uri ->
            AsyncImage(
                model = uri,
                contentDescription = "ID Card",
                modifier = Modifier.fillMaxWidth()
            )
        }
    }
}

2. Receipt/Invoice Scanning

For expense tracking or accounting apps:

@Composable
fun ExpenseReceiptScanner(
    onReceiptScanned: (Uri, String) -> Unit
) {
    DocumentScannerButton(
        onDocumentsScanned = { images ->
            images.firstOrNull()?.let { receiptUri ->
                // Extract text from receipt
                val amount = extractReceiptAmount(receiptUri)
                onReceiptScanned(receiptUri, amount)
            }
        },
        onPdfGenerated = { _, _ -> }
    )
}

3. Multi-page Document Archival

For scanning contracts, forms, or books:

@Composable
fun DocumentArchiver() {
    var documentTitle by remember { mutableStateOf("") }
    var savedPdfUri by remember { mutableStateOf<Uri?>(null) }

    Column {
        OutlinedTextField(
            value = documentTitle,
            onValueChange = { documentTitle = it },
            label = { Text("Document Name") }
        )

        DocumentScannerButton(
            onDocumentsScanned = { images ->
                // Individual pages available if needed
            },
            onPdfGenerated = { pdfUri, pageCount ->
                // Save PDF with title
                savedPdfUri = pdfUri
                saveToDocuments(documentTitle, pdfUri)
            }
        )
    }
}

4. Note-Taking Apps

Scan handwritten notes or whiteboard content:

@Composable
fun ScanAndConvertNotes() {
    DocumentScannerButton(
        onDocumentsScanned = { images ->
            images.forEach { imageUri ->
                // Use ML Kit Text Recognition
                extractHandwrittenText(imageUri) { text ->
                    // Convert to editable text
                    saveAsNote(text)
                }
            }
        },
        onPdfGenerated = { _, _ -> }
    )
}

Advanced Configuration Options

Custom Scanner Settings

// Minimal scanner (faster, less features)
val minimalOptions = GmsDocumentScannerOptions.Builder()
    .setScannerMode(SCANNER_MODE_BASE)
    .setPageLimit(1)
    .setResultFormats(RESULT_FORMAT_JPEG)
    .setGalleryImportAllowed(false)
    .build()

// Professional scanner (all features)
val professionalOptions = GmsDocumentScannerOptions.Builder()
    .setScannerMode(SCANNER_MODE_FULL)
    .setPageLimit(50)                           // Up to 50 pages
    .setResultFormats(RESULT_FORMAT_JPEG, RESULT_FORMAT_PDF)
    .setGalleryImportAllowed(true)
    .build()

Handling Different Result Formats

scanningResult?.let { result ->
    // Option 1: Process individual images
    result.pages?.forEach { page ->
        val imageUri = page.imageUri
        // Each page as separate image
        processImage(imageUri)
    }

    // Option 2: Get consolidated PDF
    result.pdf?.let { pdf ->
        val pdfUri = pdf.uri
        val pageCount = pdf.pageCount
        // Single PDF with all pages
        sharePDF(pdfUri)
    }
}

Comparison: Before vs After

Custom Camera Implementation (Old Way)

// 500+ lines of code for:
class CustomCameraActivity : AppCompatActivity() {
    private lateinit var cameraProvider: ProcessCameraProvider
    private var imageCapture: ImageCapture? = null

    // Camera setup
    // Permission handling
    // Custom UI overlay
    // Manual cropping UI
    // Image enhancement logic
    // Edge detection algorithm
    // Perspective correction math
    // Multi-page management
    // PDF generation
    // Error handling
    // ... 450+ more lines
}

Problems:

• 500+ lines of complex code
• Camera permission management
• Device compatibility issues
• Manual cropping UI needed
• No auto enhancement
• Mediocre results
• Maintenance burden

ML Kit Document Scanner (New Way)

// 10 lines of code:
val scanner = GmsDocumentScanning.getClient(options)

scanner.getStartScanIntent(activity)
    .addOnSuccessListener { intentSender ->
        launcher.launch(IntentSenderRequest.Builder(intentSender).build())
    }

// Done! Professional scanning with AI.

Benefits:

• 10 lines of code
• No permissions needed
• Works on all devices
• Auto cropping included
• AI enhancement
• Professional results
• Zero maintenance

Performance & Best Practices

Library Size Impact

ML Kit Document Scanner:  ~3MB
Custom camera + CV libs:  ~15-25MB

Worth it? Absolutely. You get professional features for 1/5th the size.

Memory Management

// Don't load all images at once
scannedImages.forEach { uri ->
    // Process one at a time
    processImage(uri)
    // Or use paging for large batches
}

// Use Coil/Glide for efficient image loading
AsyncImage(
    model = imageUri,
    contentDescription = null,
    contentScale = ContentScale.Fit
)

Error Handling

scanner.getStartScanIntent(activity)
    .addOnSuccessListener { intentSender ->
        launcher.launch(IntentSenderRequest.Builder(intentSender).build())
    }
    .addOnFailureListener { exception ->
        when (exception) {
            is MlKitException -> {
                // ML Kit specific error
                showError("Scanner unavailable: ${exception.message}")
            }
            else -> {
                // Generic error
                showError("Failed to start scanner")
            }
        }
    }

Testing on Different Devices

ML Kit Document Scanner works on:

• ✅ Android 5.0+ (API 21+)
• ✅ Devices with Google Play Services
• ✅ All form factors (phones, tablets)
• ✅ Various camera qualities

Note: Requires Google Play Services. Check availability:

fun isDocumentScannerAvailable(context: Context): Boolean {
    return try {
        val status = GoogleApiAvailability.getInstance()
            .isGooglePlayServicesAvailable(context)
        status == ConnectionResult.SUCCESS
    } catch (e: Exception) {
        false
    }
}

When to Use ML Kit vs Custom Camera

Use ML Kit Document Scanner When:

✅ Scanning documents, receipts, IDs, contracts ✅ Need professional quality scans ✅ Want multi-page support ✅ Need PDF generation ✅ Auto enhancement required ✅ Limited development time/budget

Use Custom Camera When:

⚠️ Capturing photos (not documents) ⚠️ Need real-time filters/effects ⚠️ Building a camera app ⚠️ Very specific custom workflow ⚠️ Can’t use Google Play Services

Bottom line: For 95% of document capture use cases, ML Kit is superior.

Common Pitfalls to Avoid

1. Not Checking for Play Services

// ❌ BAD - Assumes availability
scanner.getStartScanIntent(activity)

// ✅ GOOD - Check first
if (isDocumentScannerAvailable(context)) {
    scanner.getStartScanIntent(activity)
} else {
    showFallbackOption()
}

2. Ignoring URI Permissions

// ✅ Grant persistent URI permissions
contentResolver.takePersistableUriPermission(
    uri,
    Intent.FLAG_GRANT_READ_URI_PERMISSION
)

3. Not Handling Page Limits

// ✅ Set appropriate page limits
val options = GmsDocumentScannerOptions.Builder()
    .setPageLimit(
        if (multiPage) 50 else 1  // Adjust based on use case
    )
    .build()

Integration with Other ML Kit Features

Combine with Text Recognition

// Scan document, then extract text
onDocumentsScanned = { images ->
    images.forEach { imageUri ->
        recognizeText(imageUri) { extractedText ->
            // Use extracted text
            saveDocumentWithText(imageUri, extractedText)
        }
    }
}

fun recognizeText(uri: Uri, onTextExtracted: (String) -> Unit) {
    val image = InputImage.fromFilePath(context, uri)
    val recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)

    recognizer.process(image)
        .addOnSuccessListener { visionText ->
            onTextExtracted(visionText.text)
        }
}

Barcode Scanning from Documents

// Scan document with barcode/QR code
onDocumentsScanned = { images ->
    images.forEach { imageUri ->
        scanBarcode(imageUri) { barcodeValue ->
            // Handle barcode data
        }
    }
}

Quick Implementation Checklist

Before shipping document scanning to production:

• ✅ Added ML Kit dependency (~3MB)
• 📱 Tested on devices with/without Play Services
• 🔧 Configured appropriate scanner mode
• 📄 Set reasonable page limits
• 🎨 Handled both image and PDF results
• ⚠️ Implemented error handling
• 💾 Managed URI permissions properly
• 🧪 Tested with various document types
• 📏 Verified image quality/resolution
• 🔄 Added loading states for scanning

Real-World Impact

Before ML Kit:

• ⏱️ Users spent 2-3 minutes per document (capture, crop, adjust)
• 😤 30-40% required retakes due to poor quality
• 📉 High abandonment rates on document upload flows
• 🐛 Constant bug reports about scanning issues

After ML Kit:

• ⚡ 20-30 seconds per document (all automatic)
• ✨ <5% retake rate (AI handles most issues)
• 📈 50-70% improvement in completion rates
• 😊 Positive feedback about scanning experience

🔗 Related Resources

• ML Kit Document Scanner Documentation
• ML Kit Text Recognition
• Google Play Services Setup

💡 Final Thoughts

Stop wasting time building custom document capture solutions. ML Kit Document Scanner gives you professional, AI-powered scanning with minimal code.

The math is simple:

• 🕐 Custom implementation: 2-3 weeks + ongoing maintenance
• ⚡ ML Kit integration: 2-3 hours + zero maintenance
• 🎯 Result quality: ML Kit wins every time

Key takeaways:

1. Stop using basic camera capture for documents
2. ML Kit is tiny (~3MB) for massive functionality
3. 10 lines of code beats 500+ lines
4. Professional results without CV expertise
5. Users notice the difference - completion rates improve significantly

Your users deserve better than blurry, crooked photos. Give them professional document scanning with ML Kit.

That’s it! You now have the knowledge to implement professional document scanning in your Android app. 🎉

Feel free to reach out via my social handles with questions or to share your implementation! 😊

Happy scanning! 📄✨

Already know what Serena is? Here’s the fast track:

# 1. Install uv and Serena
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.zshrc
uv tool install git+https://github.com/oraios/serena

# 2. Restart terminal, then connect to your project
cd /path/to/your/project
claude mcp add serena -- serena-mcp-server --project $(pwd)
echo ".serena/" >> .gitignore

# 3. Start Claude
claude --allowedTools "mcp__serena*"

Then tell Claude: “Use Serena to onboard this project.”

Want to understand what this does and why? Read on.

A Quick Note

This is a continuation of my Claude Code notes. If you haven’t read that yet, I recommend starting there for the fundamentals. This article focuses on a specific optimization that has dramatically improved my Claude Code experience.

What you’ll learn:

• Why Claude Code can get expensive on large codebases
• How Serena uses LSP to provide semantic code navigation
• Step-by-step setup (takes ~5 minutes)
• Practical usage patterns and prompts
• When to use Serena vs. vanilla Claude Code

The Problem: Token Costs Add Up Fast

If you’ve been using Claude Code for a while, you’ve probably noticed that token costs can spiral quickly - especially on large codebases. Here’s why:

When you ask Claude something like “Where is the authentication logic?”, it often:

1. Reads entire files to understand context
2. Scans through multiple modules looking for patterns
3. Sometimes re-reads files it already looked at

For a medium-sized project (50k+ lines of code), a single exploration session can consume thousands of tokens just reading files. Multiply that across a day’s work, and you’re looking at serious costs.

Worse, when the context window fills up, Claude can start hallucinating - referencing functions that don’t exist or suggesting patterns that don’t match your codebase.

Enter Serena: Semantic Code Navigation

Serena is an open-source MCP (Model Context Protocol) server that gives Claude Code semantic understanding of your codebase. Instead of reading entire files, Claude can now:

• Jump directly to function definitions
• Find all usages of a class or method
• Navigate imports and dependencies
• Understand type hierarchies

It does this by leveraging LSP (Language Server Protocol) - the same technology that powers your IDE’s “Go to Definition” and “Find All References” features.

The Results?

In my testing on a ~100k line Android/KMP project:

That 70% isn’t marketing fluff - it’s real savings from not reading entire files when you only need specific symbols.

How Serena Works Under the Hood

MCP servers extend Claude’s capabilities through a standardized protocol (see Glossary if this is new to you). Serena specifically provides:

1. Code Indexing: When you connect Serena to Claude, it automatically builds an index of your codebase’s symbols, types, and relationships.

2. LSP Integration: Serena wraps language servers (for Kotlin, TypeScript, Python, etc.) to provide semantic navigation.

3. Smart Querying: When Claude asks “Where is UserRepository?”, Serena returns the exact file and line number - not a file dump.

4. Live Updates: The index updates as you modify code, staying in sync with your project.

┌─────────────────┐      MCP Protocol      ┌─────────────────┐
│   Claude Code   │ ◄──────────────────────► │     Serena      │
│    (Client)     │                          │   (MCP Server)  │
└─────────────────┘                          └────────┬────────┘
                                                      │
                                                      │ LSP
                                                      ▼
                                             ┌─────────────────┐
                                             │  Language Server │
                                             │  (kotlin-ls,    │
                                             │   tsserver, etc) │
                                             └─────────────────┘

One-Time Setup

Prerequisites

• Claude Code CLI installed (see my setup guide)
• A supported project (Kotlin, TypeScript, Python, Go, Rust, and more)

Step 1: Install uv Package Manager

Serena uses uv for installation. If you don’t have it:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Reload your shell
source ~/.zshrc  # or ~/.bashrc

Why uv? It’s a fast Python package manager that handles Serena’s dependencies cleanly.

Step 2: Install Serena Tools

Install the CLI tools globally:

uv tool install git+https://github.com/oraios/serena

This gives you two commands:

• serena - Project management CLI
• serena-mcp-server - The MCP server that Claude connects to

Step 3: Restart Your Terminal

Important: After installing uv and Serena, close all terminal windows and open a fresh one. This ensures your shell recognizes the new commands.

I spent time debugging “command not found” errors only to realize a terminal restart fixed everything. Save yourself the frustration.

# Close all terminals, then open a new one and verify
which serena
which serena-mcp-server

Both should return valid paths. If not, try running source ~/.zshrc (or ~/.bashrc).

Step 4: Connect Serena to Claude Code

Navigate to your project root and register Serena as an MCP server:

cd /path/to/your/project

# Add the server (this also initializes the project index automatically)
claude mcp add serena -- serena-mcp-server --project $(pwd)

What this does:

• Registers Serena as an MCP server for Claude
• Auto-initializes the project index (creates .serena/ folder)
• Scans your codebase for symbols, types, and relationships

Initial indexing time depends on project size:

You can monitor progress at http://localhost:24282 during indexing.

Important: Add .serena/ to your .gitignore. This folder is local cache and shouldn’t be committed.

echo ".serena/" >> .gitignore

Verify it’s connected:

# Check MCP server status
claude mcp list

You should see serena in the list with a green status.

Handling Permission Prompts

When you start using Serena with Claude Code, you’ll encounter multiple permission prompts. Claude asks for approval each time Serena wants to:

• Read files
• Navigate to definitions
• Search for symbols
• Access the index

This is good for security, but can get tedious during intensive coding sessions.

Option 1: Approve Permissions Individually (Recommended for Learning)

When starting out, approve each permission manually. This helps you understand what Serena is doing and builds trust in the tool.

Option 2: Auto-Accept Permissions for Serena

If you trust Serena and want a smoother experience, you can configure Claude to auto-accept its tool calls:

# Start Claude with auto-accept for the current session
claude --allowedTools "mcp__serena*"

This allows all Serena MCP tools without prompting, while still prompting for other potentially dangerous operations.

Option 3: Dangerously Skip All Permissions (Use with Caution)

For experienced users who understand the risks:

# Skip ALL permission prompts (not just Serena)
claude --dangerously-skip-permissions

Warning: This flag bypasses ALL safety prompts - file writes, shell commands, everything. Only use this if:

• You’re on a development machine (not production)
• You understand Claude can modify/delete files without asking
• You’re working in a git-tracked project (easy to revert mistakes)
• You trust your judgment to review changes before committing

For most users, Option 2 (--allowedTools "mcp__serena*") is the sweet spot - smooth Serena experience while keeping other safeguards in place.

Using Serena with Claude Code

Starting a Session

# Navigate to your project
cd /path/to/your/project

# Start Claude with Serena connected
claude

Onboarding Claude to Your Project

The first time you use Serena on a project, run this prompt:

Use Serena to onboard this project. Understand the architecture,
main modules, and key entry points.

Claude will use Serena’s semantic capabilities to build a mental model of your codebase - without reading every file.

Practical Examples

Finding specific implementations:

Where is the UserRepository interface implemented?

Without Serena: Claude reads multiple files guessing where implementations might be. With Serena: Claude jumps directly to the concrete class.

Understanding call hierarchies:

What functions call the `syncUserData()` method?

Serena traces all callers semantically, giving Claude precise context.

Navigating multi-module projects:

How does the :feature:auth module communicate with :core:network?

Serena understands module boundaries and can trace cross-module dependencies.

Monitoring and Debugging

Live Dashboard

Serena provides a local web dashboard for monitoring and debugging:

http://localhost:24282

Open this URL in your browser while Serena is running. You’ll see:

Index Status Panel

• Total symbols indexed (classes, functions, variables)
• Indexing progress percentage
• Last index update timestamp
• Any indexing errors or warnings

Query Logs

• Real-time log of Claude’s queries to Serena
• Which symbols were requested
• Response times for each query
• Helps you understand what Claude is “thinking”

Language Server Status

• Connected language servers (kotlin-ls, tsserver, etc.)
• Server health and memory usage
• Restart buttons if a server becomes unresponsive

Cache Statistics

• Hit/miss ratios
• Memory usage
• Option to clear cache if things get stale

Tip: Keep the dashboard open in a browser tab during intensive coding sessions. If Claude seems confused or slow, check the dashboard - you might spot a language server that crashed or an indexing error.

Serena Tools Available to Claude

When connected, Claude gains access to these MCP tools (you can see these with claude mcp list):

Claude automatically chooses the right tool based on your question.

Troubleshooting Common Issues

“command not found: serena” after installation:

This is the most common issue. Your terminal doesn’t know about the new commands yet.

# Option 1: Reload shell config
source ~/.zshrc  # or ~/.bashrc

# Option 2 (recommended): Close ALL terminal windows and open a fresh one
# This ensures a clean shell environment

“1 MCP server failed” error:

# Remove and re-add the server
claude mcp remove serena
claude mcp add serena -- serena-mcp-server --project $(pwd)

Index out of sync:

# Rebuild the index
serena project update --name <your-project-name>

Server not starting:

Make sure you’re in the correct project root where you ran the claude mcp add command.

Language not supported:

Check Serena’s supported languages. For Android/KMP projects, Kotlin support works out of the box.

Tip: Simplify with Aliases

These Serena commands are verbose. If you find yourself typing them often, consider setting up shell aliases or using a tool like Aliasly to manage shortcuts across projects.

Best Practices

1. Keep Your Index Updated

After major refactors or pulling new changes:

serena project update --name <your-project-name>

2. Use Specific Queries

Instead of:

How does authentication work?

Try:

Show me the AuthViewModel and its dependencies using Serena.

The more specific your query, the better Serena can target the exact symbols.

3. Combine with CLAUDE.md

Your CLAUDE.md file complements Serena perfectly. Use CLAUDE.md for:

• Project conventions and coding standards
• Build commands and configuration
• Architecture overview

Use Serena for:

• Navigating actual code
• Finding implementations
• Tracing dependencies

4. Monitor Your Savings

Use /cost in Claude Code to track your token usage. Compare sessions before and after Serena to see the actual savings.

Comparison: Claude Code vs. Claude Code + Serena

Supported Languages

Serena works with any language that has LSP support. Here’s the current status:

For Android/KMP projects, Kotlin support is what matters most - and it works great.

Note: Serena auto-detects your project’s languages and starts the appropriate language servers. You don’t need to configure this manually.

Updating and Managing Serena

Update Serena to Latest Version

uv tool upgrade serena

Rebuild Project Index

After major refactors, dependency updates, or pulling large changes:

serena project update --name <your-project-name>

Remove Serena from a Project

# Remove MCP server from Claude
claude mcp remove serena

# Delete the local index (optional)
rm -rf .serena/

Working with Multiple Projects

Serena indexes are project-specific. To switch between projects:

# Project A
cd /path/to/project-a
claude mcp add serena -- serena-mcp-server --project $(pwd)

# Project B (in a different terminal/session)
cd /path/to/project-b
claude mcp add serena -- serena-mcp-server --project $(pwd)

Each project maintains its own .serena/ index.

When NOT to Use Serena

Serena isn’t always the best choice:

• Small scripts or single-file projects: The overhead of indexing doesn’t pay off
• Heavily dynamic languages: LSP works best with typed languages
• Quick one-off questions: Sometimes just asking Claude directly is faster
• Non-code tasks: Documentation, git operations, etc. don’t benefit from Serena

Use judgment - Serena is a tool for navigating complex codebases, not a universal solution.

Integration with My Workflow

Here’s how Serena fits into my daily Claude Code usage:

1. Morning context building: “Use Serena to show me what I worked on yesterday in the :feature:dashboard module”

2. Feature development: “Using Serena, find all places where we handle network errors and show me the patterns”

3. Code review: “Navigate to the UserService implementation and review it for potential issues”

4. Debugging: “Trace all callers of processPayment() and identify where the null check might be failing”

5. Onboarding teammates: “Use Serena to explain the data flow from API response to UI state”

Cost Analysis

Let’s break down the real savings. With Claude Sonnet at ~$3/1M input tokens:

These are conservative estimates. For larger codebases or Opus usage, savings multiply significantly.

Setup Checklist

Quick reference for new projects:

• Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
• Install Serena: uv tool install git+https://github.com/oraios/serena
• Restart terminal (close all windows, open fresh)
• Verify install: which serena && which serena-mcp-server
• Connect to Claude (auto-creates index): claude mcp add serena -- serena-mcp-server --project $(pwd)
• Add to .gitignore: echo ".serena/" >> .gitignore
• Test connection: claude mcp list
• Start Claude: claude (or claude --allowedTools "mcp__serena*" to auto-accept Serena permissions)
• Onboard Claude: “Use Serena to onboard this project”

Resources

• Serena GitHub Repository
• Model Context Protocol Documentation
• My Claude Code Notes
• LSP Specification

Final Thoughts

Serena has become an essential part of my Claude Code setup. The token savings are nice, but the real value is better context preservation. Claude makes fewer mistakes when it has precise semantic information instead of guessing from partial file reads.

If you’re working on any non-trivial codebase - especially multi-module Android/KMP projects - give Serena a try. The 10-minute setup pays for itself within the first session.

As always, remember: AI is a copilot, not a pilot. Serena makes the copilot more efficient, but you’re still in control.

This article is a living document. Last updated: February 2026

Glossary

New to some of these terms? Here’s a quick reference:

MCP (Model Context Protocol)

Model Context Protocol is an open standard created by Anthropic that allows AI assistants (like Claude) to connect to external tools and data sources. Think of it as a “USB port” for AI - any tool that implements MCP can plug into Claude and extend its capabilities.

Example: Serena is an MCP server. When you run claude mcp add serena, you’re telling Claude “hey, there’s a new tool you can use.”

Learn more

LSP (Language Server Protocol)

Language Server Protocol is a standard created by Microsoft that powers IDE features like:

• “Go to Definition” (Ctrl/Cmd + Click)
• “Find All References”
• Auto-completion
• Syntax errors and warnings

Instead of each IDE implementing these features separately for every language, LSP provides a common interface. Your IDE talks to a “language server” that understands the specific language.

Example: When you Ctrl+Click a function in VS Code and it jumps to the definition - that’s LSP in action. Serena uses this same technology to give Claude semantic code navigation.

Learn more

uv

uv is a fast Python package and project manager created by Astral. It’s like npm for Python, but significantly faster (written in Rust).

Why Serena uses it: Serena is a Python project. uv tool install installs CLI tools globally, similar to npm install -g.

Key commands:

# Install a tool globally
uv tool install package-name

# Install from git repository
uv tool install git+https://github.com/user/repo

# Update a tool
uv tool upgrade package-name

Learn more

Tokens

Tokens are the fundamental units that AI models process. Roughly:

• 1 token ≈ 4 characters in English
• 1 token ≈ 0.75 words
• 100 tokens ≈ 75 words

When you send a prompt to Claude, it counts tokens. When Claude responds, it generates tokens. Both cost money with the API.

Why this matters: If Claude reads a 1000-line file to answer a simple question, that’s a lot of tokens wasted. Serena helps Claude read only what it needs.

Context Window

The context window is the maximum amount of text (in tokens) that an AI model can “remember” during a conversation. Think of it as the AI’s working memory.

Why this matters: When the context window fills up, older information gets “forgotten” or summarized. With large codebases, this can cause Claude to lose track of important details. Serena’s efficient queries help preserve context.

Semantic vs. Syntactic

• Syntactic: Understanding code as text/patterns (like grep searching for “function”)
• Semantic: Understanding code’s meaning and relationships (knowing that UserRepository implements Repository<User>)

Serena provides semantic navigation - it understands your code’s structure, not just the text.

Index / Indexing

When Serena “indexes” your project, it’s building a searchable database of your code’s structure:

• All classes, functions, and variables
• Their locations (file + line number)
• Their relationships (what calls what, what implements what)

This is similar to how search engines index websites - they pre-process content so searches are fast.

CLI (Command Line Interface)

A CLI is a text-based interface for interacting with software. Instead of clicking buttons in a GUI, you type commands.

Examples:

• git - Version control CLI
• npm - Node.js package manager CLI
• claude - Claude Code’s CLI

MCP Server vs. Client

In the MCP architecture:

• Client: The AI assistant (Claude Code) that uses tools
• Server: The tool that provides capabilities (Serena, file system access, etc.)

When you run claude mcp add serena, you’re registering Serena as a server that Claude (the client) can connect to.

Questions or feedback? Reach out:

• Email
• Website

This article is primarily a self-note that I keep updating as I learn more about Claude Code. The AI tooling landscape evolves rapidly, so some information might be outdated by the time you read this. If you find something that needs updating, feel free to reach out!

Whether you’re a junior developer just getting started or a senior developer looking to boost your workflow, Claude Code has something for everyone.

Why Should You Care?

If you’ve read my Solutionist Mindset talk, you know I believe in using AI as a copilot, not a pilot. Claude Code embodies this philosophy perfectly—it’s a CLI tool that sits alongside your existing workflow, helping you move faster while keeping you in control.

For Android and Compose Multiplatform (KMP) developers like us, having a tool that understands our codebase context is game-changing. Gradle configurations, multi-module architectures, platform-specific implementations—Claude Code can navigate all of this.

What is Claude Code?

Claude Code is Anthropic’s official CLI tool that brings Claude directly into your terminal. Unlike the web interface, it:

• Has full access to your codebase (with your permission)
• Can read, write, and edit files directly
• Runs shell commands for you
• Understands project context across multiple files
• Integrates with Git for version control operations

Think of it as having a senior developer sitting next to you who can:

• Explore your codebase instantly
• Write and refactor code
• Debug issues by reading logs and stack traces
• Create commits and PRs
• Explain complex code sections

Latest Updates (January 2026)

Update available for Claude Code users (v: 2.1.2)!

Model Selection

Opus 4.5 is now available in model selection. While Sonnet is superior for general coding tasks, Opus is amazing for complex features and crazy bugs. You can use -m flag for selecting a specific model for particular task sessions.

[!WARNING] Token Usage Warning: Continuous usage of Opus models will consume your rate limits and quota significantly faster (approx. 5-10x) than Sonnet. Use Opus only for complex debugging or architectural tasks.

# Run with a specific model
claude -m claude-opus-4-20250514

Official Plugins

Check out the official plugins:

• All Plugins
• Code Review Plugin

Getting Started

Installation

# Using npm
npm install -g @anthropic-ai/claude-code

# Using Homebrew (macOS)
brew install claude-code

After installation, run claude in your terminal to start an interactive session. You’ll need to authenticate with your Anthropic API key or use the claude --login command to login via the browser.

Basic Usage

Navigate to your project directory and simply run:

claude

This starts an interactive session where you can ask questions, request code changes, or explore your codebase.

Essential Commands Every Developer Should Know

1️⃣ Slash Commands

Claude Code has built-in slash commands that trigger specific workflows:

2️⃣ The CLAUDE.md File

One of the most powerful features for multi-module Android/KMP projects is the CLAUDE.md file. Create this at your project root:

# Project: MyKMPApp

## Architecture
- Multi-module KMP project
- Shared module: commonMain, androidMain, iosMain
- Android app module with Jetpack Compose UI
- iOS app using SwiftUI

## Key Conventions
- Use Koin for dependency injection
- Room for local database (Android), SQLDelight for shared
- Ktor for networking
- Kotlin Coroutines + Flow for async operations

## Build Commands
- `./gradlew assembleDebug` - Build Android debug
- `./gradlew :shared:build` - Build shared module only
- `./gradlew connectedAndroidTest` - Run instrumented tests

## Module Structure
- :app - Android application entry point
- :shared - KMP shared code
- :feature:home - Home feature module
- :feature:settings - Settings feature module
- :core:network - Networking utilities
- :core:database - Database layer

Claude reads this file and uses it as persistent context for every conversation. This is incredibly useful for:

• Multi-module navigation - Claude knows your module structure
• Consistent coding patterns - Follows your conventions
• Faster builds - Knows the right Gradle commands

3️⃣ Vim-Style Keybindings

For terminal enthusiasts, Claude Code supports vim keybindings:

Practical Use Cases for Android/KMP Developers

Use Case 1: Exploring Unfamiliar Codebases

When you join a new project or inherit legacy code:

You: How is the authentication flow implemented in this app?
     Show me the key files involved.

Claude will search through your codebase, identify relevant files (ViewModels, Repositories, API services), and explain the flow.

Use Case 2: Writing Compose UI Components

You: Create a bottom sheet component for filtering products.
     It should have checkboxes for categories and a price range slider.
     Follow our existing design system in :core:designsystem module.

Claude will:

1. Look at your existing design system
2. Match the patterns and naming conventions
3. Create the component following your architecture

Use Case 3: Debugging Build Issues

You: I'm getting this Gradle error when building the shared module:
     [paste error here]

     Help me understand and fix it.

Claude can read your build.gradle.kts files, understand the dependency graph, and suggest fixes.

Use Case 4: Writing Platform-Specific Implementations

You: I need to implement biometric authentication.
     Create the expect/actual declarations for Android and iOS
     in the :core:auth module.

Claude understands KMP’s expect/actual mechanism and generates appropriate platform-specific code.

Use Case 5: Creating Git Commits

You: /commit

Claude will:

1. Analyze your staged changes
2. Understand the context of modifications
3. Generate a meaningful commit message
4. Create the commit

Use Case 6: Room Database Migrations

You: I need to add a 'lastSyncedAt' column to the UserEntity.
     Create the migration and update the entity.

Claude handles the boilerplate of Room migrations, which can be error-prone manually.

Best Practices for Effective Usage

✅ DO

1. Be specific with context - Instead of “fix this bug”, say “fix the crash in UserRepository.kt when the token expires” make sure you add the file and line-number of the function or scope.

2. Review generated code - Always understand what Claude writes. Don’t blindly accept suggestions.

3. Use it for exploration - Ask Claude to explain complex parts of your codebase or third-party libraries

4. Leverage for boilerplate - Let Claude handle repetitive tasks like:

   • Creating data classes from API responses
   • Writing Room entities and DAOs
   • Setting up Hilt/Koin modules
   • Creating navigation graphs
   • Writing unit test boilerplate

5. Maintain your CLAUDE.md - Keep it updated as your project evolves

6. Use the right model for the task - Haiku for quick questions, Sonnet for general coding, Opus for complex debugging

❌ DON’T

1. Don’t share sensitive data - Avoid passing API keys, secrets, or user data through Claude

2. Don’t skip the review - Especially for security-critical code (authentication, payment processing, encryption etc)

3. Don’t use it as a crutch - You should still understand the fundamentals. AI is a multiplier, not a replacement.

4. Don’t expect perfection - Claude can make mistakes. Treat its output as a starting point.

5. Don’t ignore Gradle sync - After Claude modifies build.gradle.kts, sync manually in Android Studio

Cost Management Tips

Claude Code uses API tokens, which cost money. Here’s how to optimize:

1️⃣ Choose the Right Model

2️⃣ Use /compact Regularly

Long conversations consume more tokens. Use /compact to summarize and reduce context.

3️⃣ Start Fresh for New Tasks

Use /clear when switching to unrelated tasks. No need to carry previous context.

4️⃣ Be Concise

Instead of:

"Hey Claude, I was wondering if you could maybe help me
understand how the user authentication works in this app,
like when someone logs in, what happens step by step?"

Try:

"Explain the login flow. Start from LoginViewModel."

6️⃣ Offload Tasks to Other Models/Tools (Save those Tokens!)

Not everything requires Claude Code’s deep context awareness. Save your tokens by routing tasks to the right tool:

• Use Gemini for Quick Concepts: Need to understand “How LruCache works internally” or “Explain the Builder pattern”? Use Gemini. It’s fast, free/cheap, and great for general knowledge that doesn’t need your private codebase context.
• Use ChatGPT for High-Level Project Questions: If you need advice on “Best practices for modularizing a KMP project” or architecture discussions where providing full code access isn’t necessary, ChatGPT is a great option.
• Use CLI Tools for Quick Answers: If you’re a terminal power user (using tmux, dia, etc.), tools like ddgr (DuckDuckGo from terminal) or Ollama (local models) are fantastic for quick lookups without leaving your flow.

[!TIP] Pro Tip: Reserve Claude Code for tasks that specifically need to read your files, understand your project structure, or perform edits. For everything else, cheaper (or free) alternatives often work just as well!

7️⃣ Check Costs with /cost

Regularly run /cost to monitor your usage.

Integration with Development Workflow

IDE Integration

Claude Code works alongside your IDE, not inside it. A typical workflow:

1. Have your IDE open (Android Studio / Fleet / IntelliJ)
2. Run Claude in a terminal (split screen works great)
3. Ask Claude to make changes
4. Review changes in IDE (they appear instantly)
5. Test and iterate

Git Workflow Integration

Claude Code integrates nicely with Git:

# Start a session
claude

# Create meaningful commits
You: /commit

# Create a pull request
You: Create a PR for these changes. The target branch is develop.

# Review code before pushing
You: Review the changes in the last commit for any issues.

Common Gotchas for Android/KMP Projects

1️⃣ Gradle Sync After Changes

When Claude modifies build.gradle.kts files, you’ll need to sync in Android Studio manually. Claude can’t trigger this for you.

2️⃣ Resource Files

Claude can create/modify XML resources (layouts, strings, drawables), but be careful with:

• Generated resources (R class) - These regenerate on build
• Vector drawables - Complex paths might need manual tweaking

3️⃣ Compose Preview

Claude-generated Compose components might need @Preview annotations added for visibility in Android Studio’s preview pane.

4️⃣ iOS-Specific Code

For KMP projects, Claude can write Swift/Objective-C code for iOS implementations, but:

• You’ll need Xcode to verify it compiles
• Swift interop with Kotlin can be tricky

5️⃣ Version Catalog

If you use libs.versions.toml, make sure Claude knows about it in your CLAUDE.md. Otherwise, it might use hardcoded versions.

My Personal Workflow

Here’s how I typically use Claude Code for Android development:

1. Morning exploration - “What did I work on yesterday? Show me recent changes.”

2. Feature development - Start with asking Claude to explore existing patterns, then implement following those patterns

3. Code review helper - “Review this ViewModel for potential memory leaks or coroutine issues”

4. Documentation - “Generate KDoc comments for the public methods in NetworkClient.kt”

5. Refactoring - “Migrate this callback-based API to use Kotlin Coroutines with Flow”

6. Test writing - “Write unit tests for UserRepository using MockK”

Advanced: MCP Servers

Claude Code supports Model Context Protocol (MCP) servers, which extend its capabilities. For Android developers, interesting MCPs include:

• File system access - Already built-in
• Git operations - Built-in
• Web search - For documentation lookups
• Custom tools - You can create your own MCP servers

Check out the MCP Documentation for more details.

Useful One-Liners

Quick commands I use frequently:

# Start with a specific model for complex tasks
claude -m claude-opus-4-20250514

# Resume last conversation
claude --resume

# Check installation health
claude /doctor

# Quick code review
claude "Review my staged changes for issues"

What’s Next?

This article covers the fundamentals, but Claude Code is constantly evolving. I plan to update this note as I discover:

• New features and capabilities
• Better workflows for KMP development
• Integration patterns with CI/CD
• Team collaboration strategies

Final Thoughts

Claude Code is a powerful addition to the Android/KMP developer toolkit. It’s not about replacing your skills—it’s about amplifying them. Use it to handle boilerplate, explore unfamiliar code, and move faster on repetitive tasks.

But remember: You are still the pilot. Claude is your copilot. Understand what it generates, review its suggestions, and keep learning the fundamentals.

The developers who thrive in the AI age won’t be those who code the fastest—they’ll be the ones who solve problems thoughtfully while leveraging every tool at their disposal.

Resources

• Official Claude Code Documentation
• Claude Code GitHub
• Official Plugins
• Model Context Protocol
• My Solutionist Mindset Talk

Feel free to connect with me on: 📩 Email 🌍 Website

I wish to keep this article as a living document. Last updated: January 2026

The green hyperlinks are clickable

Pretty straightforward, right? Just a bit of text with two clickable links — Privacy Policy and Terms of Service.

But as I started implementing it, I realized: there isn’t a single complete guide explaining how to make part of a text clickable using AnnotatedString in Jetpack Compose — especially with the new LinkAnnotation API and a custom URL handler for better control.

So I’m writing this as both a reference for myself and for anyone else struggling with this tiny, under-documented detail.

Why Custom URL Handling?

By default, Compose can open links using the system browser. But what if you want:

• Better UX with Chrome Custom Tabs (opens links in-app with smooth transitions)
• Graceful fallbacks (handle cases where browsers aren’t installed)
• Full control over how URLs are opened (analytics, deep links, etc.)

That’s exactly what we’ll implement.

Step-by-Step Implementation

1. Add the Browser Library

We’ll use Android Browser Library to implement Chrome Custom Tabs for a better link-opening experience.

Add this to your libs.versions.toml:

[versions]
browser = "1.8.0"

[libraries]
androidx-browser = { group = "androidx.browser", name = "browser", version.ref = "browser" }

Then add the dependency to your app’s build.gradle.kts:

dependencies {
    implementation(libs.androidx.browser)
}

Why Chrome Custom Tabs? Custom Tabs open web content inside your app with a smooth transition, pre-loaded browser engine, and shared cookies/sessions — all without leaving your app’s context.

2. Create a Custom URL Handler

This function handles opening URLs with three layers of fallback:

fun urlHandler(url: String, context: Context) {
    try {
        // First: Try Chrome Custom Tabs (best UX)
        val customTabsIntent = CustomTabsIntent.Builder().build()
        customTabsIntent.launchUrl(context, Uri.parse(url))
    } catch (e: ActivityNotFoundException) {
        try {
            // Second: Fallback to system browser
            val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
            context.startActivity(intent)
        } catch (e: Exception) {
            // Third: Show toast if no browser exists
            Toast.makeText(
                context,
                "Browser not installed! visit: $url",
                Toast.LENGTH_LONG
            ).show()
        }
    } catch (e: Exception) {
        e.printStackTrace()
        Toast.makeText(
            context,
            "Unable to open link! visit: $url",
            Toast.LENGTH_SHORT
        ).show()
    }
}

How it works:

1. Chrome Custom Tabs (preferred): Opens in-app with native feel
2. System Browser (fallback): Opens in the default browser if Custom Tabs fail
3. Toast Message (last resort): Shows URL if no browser is available

This ensures your app never crashes when opening links, even on devices without browsers.

3. Building the Clickable Text Component

Now let’s create the actual composable with clickable links.

@OptIn(ExperimentalTextApi::class)
@Composable
internal fun TermsAndCondition() {
    val context = LocalContext.current

    // Define how links should behave when clicked
    val linkInteractionListener = LinkInteractionListener {
        urlHandler((it as LinkAnnotation.Url).url, context)
    }

    // Define link styling (color + underline)
    val linkStyle = TextLinkStyles(
        SpanStyle(
            color = DGreen,
            textDecoration = TextDecoration.Underline
        )
    )

    // Create Privacy Policy link annotation
    val privacyPolicy = LinkAnnotation.Url(
        url = URLS.PRIVACY,
        styles = linkStyle,
        linkInteractionListener = linkInteractionListener
    )

    // Create Terms of Service link annotation
    val toc = LinkAnnotation.Url(
        url = URLS.TOC,
        styles = linkStyle,
        linkInteractionListener = linkInteractionListener
    )

    // Helper functions for reusable link text (supports localization!)
    @Composable
    fun AnnotatedString.Builder.privacyLink() {
        withLink(privacyPolicy) {
            append(stringResource(id = R.string.privacy_policy))
        }
    }

    @Composable
    fun AnnotatedString.Builder.tocLink() {
        withLink(toc) {
            append(stringResource(id = R.string.terms_of_service))
        }
    }

    // Build the complete annotated string with mixed text + links
    val annotatedString = buildAnnotatedString {
        append("Read ")
        privacyLink()  // Clickable Privacy Policy
        append(" and tap on `")
        withStyle(style = SpanStyle(fontWeight = FontWeight.Bold)) {
            append("Agree and Continue")
        }
        append("` to accept the ")
        tocLink()  // Clickable Terms of Service
    }

    Text(
        text = annotatedString,
        style = PannaiTheme.typography.semiBold12.copy(
            color = LGray,
            textAlign = TextAlign.Center
        ),
        modifier = Modifier.fillMaxWidth(0.8f),
    )
}

Breaking Down the Code

LinkInteractionListener

val linkInteractionListener = LinkInteractionListener {
    urlHandler((it as LinkAnnotation.Url).url, context)
}

• This listener gets triggered when any link is clicked
• It extracts the URL from the LinkAnnotation.Url object
• Passes it to our custom urlHandler() for controlled opening

LinkAnnotation.Url

val privacyPolicy = LinkAnnotation.Url(
    url = URLS.PRIVACY,
    styles = linkStyle,
    linkInteractionListener = linkInteractionListener
)

• url: The actual link destination
• styles: How the link looks (color, underline, etc.)
• linkInteractionListener: What happens when clicked

This is the new Compose way of handling links (replaces older pushStringAnnotation approach).

Helper Functions for Localization

@Composable
fun AnnotatedString.Builder.privacyLink() {
    withLink(privacyPolicy) {
        append(stringResource(id = R.string.privacy_policy))
    }
}

Why helper functions? By using stringResource(), the link text automatically updates based on user’s language. This makes your code cleaner, reusable, and supports multi-language apps without duplicating logic.

Building the Final Text

val annotatedString = buildAnnotatedString {
    append("Read ")
    privacyLink()  // This part is clickable!
    append(" and tap on `")
    withStyle(style = SpanStyle(fontWeight = FontWeight.Bold)) {
        append("Agree and Continue")
    }
    append("` to accept the ")
    tocLink()  // This part is also clickable!
}

This combines regular text + clickable links + styled text in one component. withLink() wraps text and makes it interactive, while withStyle() applies visual formatting without making it clickable.

Key Takeaways

• LinkAnnotation API is the modern way to create clickable links in Compose
• Custom URL handler gives you full control over how links open
• Chrome Custom Tabs provides better UX than default browser
• Graceful fallbacks prevent app crashes on edge cases
• Helper functions + stringResource make your code localization-ready

Why This Approach is Better

Compared to older methods using pushStringAnnotation, this approach:

• Type-safe: LinkAnnotation is strongly typed
• Easier styling: Direct style application per link
• Better separation: Link logic separate from text building
• Localization-friendly: Works seamlessly with multi-language apps

Related Resources

• LinkAnitation Documentation
• Chrome Custom Tabs Guide

Thanks for reading! If you found this helpful, feel free to reach out via my social handles.

Presenting the Solutionist Mindset on stage

Standing on that stage at DevFest2025 in Chennai, looking out to you all, I asked a simple question: “How many of you are worried about AI taking over your job?”

The show of hands was overwhelming (some shared why they are confident too, I wish I was them). The anxiety in the room was palpable.

I get it. I’ve been there. In fact, I’m still navigating these waters myself. As an Android Developer at Zoho, I’ve watched AI tools evolve from curiosities to formidable coding partners. They’re impressive—spitting out code 10 to 100 times faster than we can. It’s almost unsettling, watching something produce in minutes what would take us hours or days.

The predictions are scary. The layoff numbers are even scarier. Tech Twitter is full of doom-scrolling material about how AI will replace developers, how junior positions are vanishing, how the barrier to entry is impossibly high now.

So I did what any rational person would do—I took a step back and contemplated this deeper.

What’s the worst thing that can happen to me?

And then I realized something profound: I’ve been through worse.

Rock Bottom: Varanasi, December 2017

Let me share something deeply personal with you. Something I don’t talk about often, but something that fundamentally changed how I approach adversity.

In December 2017, my life fell apart.

Not in the dramatic, movie-like way—but in the quiet, suffocating way that creeps up on you. Emotionally stuck, I watched as friends I believed would be with me forever just… disappeared. The community I had built my identity around crumbled. My entire belief system, everything I thought I knew about life and relationships, shattered.

Losing all hope, I set out on what I genuinely thought would be my final journey: to Varanasi.

The Ghats of Varanasi

I spent weeks alone at the ghats with almost nothing. It was the coldest winter I’ve ever experienced, and I wasn’t prepared—not physically, not mentally, not emotionally.

Surviving on just one meal a day at a nearby temple, I would spend my days sitting by the river, gazing into the Ganges in silence. The helplessness, the solitude—it was unlike anything I had ever known before. Even now, years later, I struggle to put that experience into words.

Imagine this: You’re standing at the crossroads of chaos. Motion swirls all around you—boats on the river, pilgrims performing rituals, the constant murmur of life and death existing side by side. Yet despite all this movement, you’re paralyzed. You can’t decide where to step next. Your mind feels numb. The whole experience is so overwhelming that language itself becomes inadequate.

But here’s what that experience taught me: Clarity doesn’t come from escaping pain. It comes from sitting with it, accepting it, and taking it in as a lesson from the universe.

When you’ve sat at the ghats of Varanasi, contemplating the impermanence of everything while watching funeral pyres burn and pilgrims bathe, the fear of losing a job to AI becomes… manageable. Not trivial—but definitely manageable.

Fast Forward: Finding Auroville

After a few more reality checks and life lessons (because apparently, Varanasi wasn’t enough), I came across Auroville and its unique philosophy around money and community living.

For those unfamiliar, Auroville is an experimental township in Tamil Nadu, founded on the principles of human unity, sustainable living, and spiritual evolution. Their approach to money and work fascinated me—the idea that work should be about contribution, not just compensation.

I felt drawn to it. It seemed like a place that resonated with what I was searching for—a new way of living, a new framework for understanding my place in the world.

Reality Meets Philosophy

When I arrived, I realized that while the philosophy was inspiring, it was still very much a work in progress—an idea in the process of becoming real. The gap between the ideal and the reality was significant. But you know what? That’s okay. That’s how all great experiments work.

Yet, amidst that gap, I found something invaluable: a warm, accepting community and my very first job at a busy guest house.

I started as a waiter. Then I worked my way up—biller, receptionist, whatever was needed. Each role taught me something new about human interaction, problem-solving, and the simple dignity of work.

It was genuinely educative in ways a classroom never could be. I learned about hospitality, about managing stress during rush hours, about the intricate dance of keeping customers happy while maintaining operational efficiency.

But there was one problem that bugged me daily, especially at the billing counter.

My First Solution: The Python Calculator

Restaurants in Auroville had unique discount structures that reflected their community-oriented values:

• 10% off for volunteers
• 20% off for Auroville residents
• Plus 5% GST for regular guests

Simple enough, right? Except during rush hours, when we had to calculate all this manually using a calculator.

Picture this: It’s lunch rush. The kitchen is yelling that orders are backing up. Customers are waiting, getting increasingly impatient. You’re trying to calculate percentages on a basic calculator while keeping track of multiple bills, and someone changes their mind about their order halfway through.

It was absolute chaos.

So, I did something I had never done before—I wrote a simple Python Tkinter app to simplify this process.

The Joy of Building Your First Solution

Now, to any experienced developer reading this, a Python Tkinter calculator probably sounds laughably simple. And it is. But back then, for someone with minimal programming experience, it was transformative.

It took me a couple of days and several iterations. The first version was buggy. The UI was ugly. But it worked. And during the next busy lunch rush, it saved my sanity.

This was my first real solution. Not a tutorial project. Not a homework assignment. A real problem, solved with real code, that helped real people.

Looking back now, it’s not sparkly or impressive. I wouldn’t put it in my portfolio. But it was a huge milestone in my journey. It empowered me to believe that I could build tools to solve problems.

The AI Comparison

Here’s the kicker: If I faced the same problem today, with access to Claude, GPT-4, or Copilot, it would take me 5 minutes or less to build the same thing. Probably better, with proper error handling and a cleaner UI.

That’s both amazing and terrifying. Amazing because of the productivity boost. Terrifying because if I were starting my journey today, would I have learned the same lessons? Would I have struggled enough to truly understand the fundamentals?

This is the paradox we’re living in.

The Bootcamp: Zoho Schools of Graduate Studies

After a while working at the restaurant, things were getting repetitive. I could do the job in my sleep. The initial learning curve had flattened out completely.

Then, I was given an opportunity to participate in the Zoho Schools of Graduate Studies (ZSGS)—a pilot 3-month fast-track program into software development.

There were interviews. There were coding tests. There were problem-solving assessments.

But you know what stood out during my interview? That custom calculator project I built to solve the billing problem.

It wasn’t the fanciest project. It wasn’t built with the latest framework or deploying cutting-edge architecture. But it demonstrated something crucial: I could identify a problem and build a solution.

The Underdog Journey

With a few more rounds of interviews and small projects, I was accepted into the program. But here’s the thing—acceptance didn’t guarantee employment at Zoho. It just meant you’d get direct interviews if there were openings afterward.

And I wasn’t under any illusion about my chances.

I was the only individual with just an SSLC (10th grade) certificate among some incredibly bright minds with degrees in Computer Science, Electronics, Mathematics, and various other technical streams. On paper, I was the least qualified person in that room.

But I knew one thing: I could give my absolute best and absorb everything like a sponge.

I was like a thirsty man stumbling upon an oasis—desperate to quench my thirst by learning everything I possibly could.

The Learning Environment

The program was intense. We learned data structures, algorithms, software design principles, databases, and practical software development. But more than the technical content, it was the mindset shift that mattered.

My mentors didn’t just teach me how to code—they taught me how to think. How to break down complex problems. How to ask the right questions. How to learn independently.

The other students, despite their impressive credentials, were incredibly supportive. We learned from each other, challenged each other, and grew together.

Thanks to my mentors and the collaborative environment, I managed to not just survive, but thrive.

The Interview

And the first team that interviewed me at the end of the program? They took me in.

Not because of my credentials (I had none). Not because of my degree (I had none). But because I demonstrated the ability to learn, adapt, and build solutions.

That’s how I became part of this wonderful tech world. Not through traditional credentials, but through small projects, relentless learning, and incredible mentors who saw potential where others might have seen only limitations.

A Glimpse of Tech Life

After joining a team at Zoho, I slowly started getting accustomed to this new life—realizing how incredibly fortunate I was to be on an autodidactic journey that felt like a dream.

Learning, growing, and getting paid for it? It seemed almost too good to be true.

The Difference from Previous Jobs

Unlike any job I’d had before—waiter, receptionist, biller—this one was fundamentally different. Everything I learned for work actually empowered me personally. It felt like one of those rare systems where the more you give, the more you grow.

It was like tending a bonsai tree—carefully shaped by external constraints and guidance, yet every bit of effort you put in feeds your own roots, strengthens your own foundation.

I was getting paid to:

• Learn new technologies
• Experiment with different approaches
• Build features that many would use
• Solve genuinely interesting problems

It felt unreal. It felt like the job I had dreamed about during those cold nights in Varanasi.

The Honeymoon Phase

For a couple of years, it was blissful. The learning curve was steep but manageable. Android development was evolving rapidly—Kotlin was gaining traction, Jetpack Compose was being introduced, and the ecosystem was thriving.

I threw myself into it. I learned Kotlin inside and out. I became proficient in Android architecture patterns. I contributed to significant features in our products.

For a while, I felt secure. I had carved out expertise. I had value.

And then… the AI wave hit.

Then AI Happened

ChatGPT launched in November 2022. At first, it was a curiosity. We played with it, asked it silly questions, marveled at its responses.

Then GitHub Copilot became mainstream. Then GPT-4 arrived. Then Claude. Then specialized coding models like Codex and Replit Ghostwriter.

Watching AI get better at coding, debugging, and doing things that used to be uniquely ours—suddenly, that old fear came back.

Not the fear of losing everything (I’d survived that in Varanasi). But the fear of becoming irrelevant was just as scary in a different way.

The Existential Questions

What happens when the skills we’ve painstakingly built over years suddenly don’t matter anymore?

What happens when a fresh graduate with AI assistance can be as productive as a senior developer?

What happens when companies realize they can maintain codebases with fewer people because AI handles the routine work?

These weren’t hypothetical questions anymore. They were becoming reality. The layoff announcements from major tech companies included explicit mentions of “productivity improvements through AI” as justification.

The Essay That Changed My Perspective

Around that time, in one of our team discussions about the future of software development, my manager shared an essay from 1932 by Bertrand Russell called “In Praise of Idleness.”

Has anyone here read it? If not, I highly recommend it.

Russell wrote this during the Great Depression, when millions were unemployed and the world was in economic turmoil. Yet his argument wasn’t about working harder to save the economy—it was about working smarter and questioning the entire premise of constant labor.

Russell’s Radical Idea

Russell argued that modern civilization had created a moral trap where we measure human worth by hours worked, not by problems solved or lives improved.

He believed that if machines could handle labor, we shouldn’t artificially create more meaningless work just to keep people busy. Instead, we should use that freedom for:

• Creativity
• Learning
• Art
• Philosophy
• Solving problems that actually matter

Think about that. Written in 1932, before:

• Computers
• The Internet
• Mobile phones
• Artificial Intelligence

Yet it feels like it was written specifically for us, right now, in 2025.

The Question Reframed

Russell’s essay helped me reframe the question entirely.

It’s not “Will AI replace us?”

It’s “What will we do with the freedom AI creates?”

Tasks that used to take weeks or months of research, development, and iteration now take hours or days thanks to AI assistance.

Yes, there will be side effects:

• Layoffs
• Reduced entry-level positions
• Increased pressure on individual productivity
• Market corrections

But these aren’t permanent states—they’re transition periods. And the question for each of us is: How do we position ourselves to thrive in this transition?

Breaking Out of the Box

For years, I had confined myself to what I call a “boxed developer” mindset.

Everything revolved around:

• Kotlin
• Android
• Jetpack Compose

I was good at it. I was comfortable. I could solve most Android problems thrown my way.

But I realized that comfort was becoming a cage.

The Title Trap

We do this to ourselves, don’t we? We accept titles and roles that become our entire identity:

• “I’m an Android Developer”
• “I’m a Frontend Engineer”
• “I’m a Backend Specialist”

These titles are useful for resumes and LinkedIn profiles. They help us find jobs. They give us a sense of expertise.

But they also limit our view. They keep us from looking beyond what our immediate work needs us to see.

Developer vs. Solutionist

Here’s the crucial distinction I’ve discovered:

A developer writes code to win bread. They learn what they need to stay employed. They specialize to remain valuable. It’s transactional.

A solutionist goes much deeper. They enjoy and learn every bit they can, like a magnet drawn to new knowledge. They’re driven by curiosity and the joy of solving problems, not just by paychecks.

The developer asks: “What do I need to know for my job?”

The solutionist asks: “What do I need to know to solve this problem effectively?”

See the difference?

Staying Relevant: Build Continuously

This distinction matters immensely because once the AI tsunami completes its first wave, the next one is already forming.

Quantum computing advancements. More sophisticated AI models. New paradigms we haven’t even conceived of yet.

Staying relevant through all of these requires constant adaptation and learning.

My proposition for navigating this? BUILD CONTINUOUSLY.

Why Build More?

Because what better way to learn than building projects?

Not theoretical knowledge. Not tutorial hell. Not certifications that gather dust.

Actual projects that solve real problems faced by real humans (even if that human is just you).

The Compounding Effect of Small Projects

Just like that simple billing calculator I mentioned earlier—you never know where a small project might lead.

After experiencing the joy of building that first solution, I built many more:

• A personal expense tracker (because existing ones didn’t fit my mental model)
• A community link-sharing platform (to solve coordination problems in my friend group)
• A personal task management system (because I needed something simpler than Notion but more structured than notes)
• Various automation scripts for repetitive tasks

All of these are available on my website. Are they perfect? Absolutely not. Do they have bugs? Definitely. Are they going to change the world? Probably not.

But they’ve changed my world.

What Building Teaches You

Building small things consistently transforms you:

1. You see problems differently - Instead of complaining about inefficiencies, you see opportunities to build solutions.

2. You stop feeling stuck - There’s always something you can build, always some small improvement you can make.

3. You develop taste - You understand what makes software feel good to use because you’re both the builder and the user.

4. You become resilient - When things break (and they will), you learn to fix them. When approaches don’t work, you pivot.

5. You evolve unexpectedly - You slowly become someone you didn’t know you could become. Skills compound. Confidence grows.

So, What Is a Solutionist?

After all these stories and reflections, let me give you a concrete definition:

A Solutionist isn’t defined by tools, but by problems solved.

They are:

• Language-agnostic
• Framework-flexible
• System-aware
• Problem-focused

The Four Traits of a Solutionist

Through my journey and observation of people I admire, I’ve identified four core traits:

1. Empathy — Understanding People, Not Just Specs

The best solutions come from understanding the human problem, not just the technical specification.

This means:

• Putting yourself in the user’s shoes
• Understanding their frustrations, not just their feature requests
• Recognizing that “make it faster” often means “I feel frustrated waiting”
• Seeing the emotional journey, not just the user journey

When I built that billing calculator, I wasn’t solving a math problem. I was solving the stress and anxiety of my colleagues during rush hours.

2. Systems Thinking — Seeing Ripple Effects

Nothing exists in isolation. One change ripples through everything.

Systems thinking means:

• Understanding dependencies and consequences
• Recognizing that “fixing” one thing might break another
• Seeing the whole forest, not just the tree you’re debugging
• Appreciating long-term implications of short-term decisions

In Android development, this might mean understanding how a seemingly innocent change in a shared ViewModel might affect multiple screens, or how a database migration could impact app startup time.

3. Lifelong Learning — Venturing Into the Unknown Without Fear

The moment you stop learning, you start becoming obsolete.

Lifelong learning means:

• Being comfortable with being a beginner again and again
• Exploring technologies outside your comfort zone
• Reading papers, essays, and documentation for things you don’t “need” yet
• Understanding that every new skill multiplies with every previous skill you’ve learned

From SSLC certificate to Android Developer to exploring AI/ML, backend systems, DevOps—each layer adds new dimensions to how you solve problems.

4. Communication — Bridging Technical and Non-Technical Minds

The best solution is useless if no one understands it.

Communication means:

• Explaining complex technical concepts to non-technical stakeholders
• Writing documentation that actually helps
• Listening actively to understand requirements beneath the surface
• Collaborating effectively across disciplines—design, product, business

I’ve seen brilliant solutions fail because they were explained poorly. And I’ve seen simple solutions succeed because they were communicated effectively.

AI as Freedom: Russell’s Prophecy Coming True

When AI arrived, many feared job loss. And yes, that’s happening in some sectors.

But what if Russell was right all along?

What AI Actually Removes

AI removes:

• Repetitive, mechanical work
• Boilerplate that makes our days feel routine
• The cognitive load of remembering syntax
• The tedium of debugging simple logic errors

It gives time back for:

• Creativity
• Empathy
• Real problem-solving
• Strategic thinking
• Learning deeply instead of superficially

Vibe Coding: Thanks to Andrej Karpathy

This is where ‘vibe coding’ comes in—a term popularized by Andrej Karpathy.

Let AI help you move faster. Let it handle the repetition, the boilerplate, the syntax you can never quite remember.

But—and this is crucial—understand what it’s changing.

Know the patterns. Understand the tweaks. Grasp the reasoning behind every line it suggests.

The Danger of Blind Coding

If you code blindly, just accepting whatever AI suggests without understanding:

• You lose the joy of building
• You become oblivious to your own vision
• You can’t debug effectively when things inevitably break
• You stop learning and start copy-pasting

AI should be your copilot, not your pilot. You’re still flying the plane.

How to Actually Start: Practical Steps

Enough philosophy. Let’s talk practically.

Want to build something? Here’s what I’ve learned through building multiple projects with AI assistance:

Step 1: Start with the Problem

Write it down. Not the solution—the problem.

Ask yourself:

• What are you trying to solve?
• Who are you solving it for?
• Why does this problem matter?
• What does success look like?

Be specific. “I want to build a todo app” is not a problem. “I keep forgetting to follow up on important emails, and existing todo apps don’t integrate well with my email workflow” is a problem.

Step 2: Document Your Vision First

Before you write a single line of code, create a clear vision of what you’re building and why.

Your first commit should be your vision, not your code.

This document becomes your North Star. When AI suggests clever solutions that drift from your vision, you can catch it. When scope creep tempts you, you can resist it.

Step 3: Use AI to Move Fast, But Understand Everything

This is the balance:

• Let AI generate boilerplate → But understand the structure it creates
• Let AI suggest solutions → But understand why those solutions work
• Let AI write tests → But understand what they’re testing and why

Know the patterns. Understand the tweaks. Grasp the reasoning behind every line.

If you find yourself accepting suggestions without understanding them, stop. Research. Learn. Only then proceed.

Step 4: Iterate Deliberately

Add features one at a time.

Track changes with Git. See what’s happening at each step.

This isn’t just about version control—it’s about understanding the evolution of your project. Each commit is a story. Each feature is a chapter.

Deliberate iteration means:

• Build one thing
• Test it thoroughly
• Document what you learned
• Commit it
• Move to the next thing

Step 5: The Tools Don’t Matter. The Mindset Does.

I cannot stress this enough.

The language doesn’t matter. The framework doesn’t matter. The cloud provider doesn’t matter.

What matters is:

• Do you understand the problem?
• Does your solution solve it effectively?
• Can you explain why you made the choices you made?
• Did you learn something building it?

That’s all that matters.

The Real Power: Wearing All the Hats

When you build your own projects, you’re not just a developer.

You’re everything:

• Visionary — Defining what should exist
• Product Manager — Prioritizing features
• Designer — Crafting the experience
• Developer — Building the solution
• QA — Testing and breaking things
• DevOps — Deploying and maintaining
• Support — Handling bugs and feedback

The Freedom This Gives You

Maybe you’ll build something the world uses. Maybe not.

Either way, it’s yours. It’s your journey.

In a typical software job, you might not get to wear all these hats due to company policies and defined roles. You’re the “backend developer” or the “mobile engineer” or the “frontend specialist.”

But here, on your own project, you are the boss. The founder. The everything.

This level of ownership is both daunting and incredibly empowering.

The Career Impact

I’m certain that this experience—building complete projects from vision to deployment—will help you solve day-to-day professional problems much faster.

Because you’ve seen the whole picture. You understand how the pieces fit together. You’ve debugged across the stack. You’ve made tradeoffs and lived with the consequences.

That holistic understanding is invaluable and increasingly rare in our specialized world.

Start Today: Your Action Items

Don’t wait. Don’t prepare. Don’t plan endlessly.

Start small. Start now.

Pick One Frustrating Problem

Look at your daily life. What frustrates you repeatedly?

• Tracking expenses?
• Managing reading lists?
• Coordinating with friends?
• Remembering to water plants?
• Finding recipes based on ingredients you have?

Pick one. Just one.

Don’t Chase Perfection. Chase Progress.

Your first version will be ugly. It will have bugs. It will be embarrassing to show others.

Build it anyway.

Because version 0.1 is infinitely better than the perfect app that exists only in your imagination.

Use Every Project as a Playground

Want to learn a new framework? Use it for your next project.

Curious about a new database? Try it.

Interested in a new deployment strategy? Experiment.

Every project is an opportunity to play, to experiment, to learn.

Every Problem Solved Is Progress

Each problem solved is one step closer to being a Solutionist.

Not because you’re accumulating credentials or certificates, but because you’re training yourself to see opportunities where others see obstacles.

Closing: Reclaiming Purpose

When my manager first sent me “In Praise of Idleness,” I thought it was ironic. Here we are, working in tech, and he’s sending me an essay about working less?

Now I see the wisdom.

It’s not about doing less. It’s about doing better.

It’s about focusing on work that matters, that challenges us, that makes us grow.

What AI Can’t Replace

We’ve built technology powerful enough to automate tasks, but not powerful enough to replace people who bring meaning to them.

AI can:

• Write code
• Debug programs
• Architect systems
• Generate tests
• Refactor codebases

But it can’t:

• Understand why we build
• Feel empathy for users
• Ask deeper questions about impact
• Navigate the human complexities of real projects
• Find purpose in the work

That’s still our job. Always will be.

The World Needs Solutionists

The world doesn’t just need coders. We have enough people who can write syntactically correct code.

The world needs people who:

• See problems and craft thoughtful solutions
• Combine empathy with engineering
• Explore fearlessly and learn relentlessly
• Ask “why” as often as they ask “how”
• Reclaim purpose in a world obsessed with productivity

Don’t Confine Yourself to a Box

So don’t confine yourself to a box labeled “Android Developer” or “Frontend Engineer” or “Data Scientist.”

Explore. Venture into the unknown.

Build. Create things that matter to you.

Reflect. Learn from what works and what doesn’t.

Be a Solutionist.

Because the world doesn’t just need more developers.

It needs you.

Thank You

First and foremost, a huge thank you to Google Developer Group Chennai for organizing DevFest2025 and giving me this incredible platform to share my journey and thoughts with the community.

To all the volunteers who worked tirelessly behind the scenes—setting up the venue, managing logistics, helping attendees, and ensuring everything ran smoothly—you are the unsung heroes who make events like this possible. Your dedication and energy created the welcoming atmosphere that made DevFest2025 special.

A special thanks to all the sponsors who believed in this event and invested in our developer community. Your support makes it possible for us to gather, learn, share, and grow together.

To the GDG Chennai organizers and core team members—thank you for building and nurturing this vibrant tech community in Chennai. Your consistent efforts to bring developers together, facilitate learning, and create opportunities for knowledge sharing are truly invaluable.

To everyone who attended the talk and engaged with these ideas—your questions, your reflections, your nodding heads, and even your skeptical looks made this talk so much more meaningful. The conversations we had afterward were some of the most enriching parts of the entire experience.

And to you, reading this now—whether you attended DevFest2025 or are discovering this for the first time—I hope something here resonates. I hope it sparks something in you.

Now let’s build something.

Sone of the feedbacks from Participants

Heartwarming feedback from the DevFest2025 participants

Event Highlights

Here are some moments from DevFest2025:

The announcement that started it all

Sharing the Solutionist Mindset with the DevFest2025 community

Presenting the Solutionist Mindset on stage

Engaging with the audience during the talk

A memorable moment from DevFest2025

All the amazing volunteers who made DevFest2025 possible - couldn’t have done it without you!

The speaker goodies bag - thanks GDG Chennai! For everyone who asked what’s inside: GDG swag, stickers, and some awesome tech goodies!

If you want to discuss any of these ideas further, or if you’re building something and want to share your journey, feel free to reach out. I’m always excited to connect with fellow solutionists.

All my projects are available on my website. They’re not perfect, but they’re mine, and they’re continuously evolving. Just like me. Just like you.

This guide will walk you through the basics of Nginx, explaining its structure and showing you how to set up your very first website.

1. Installation

If you haven’t already, you can install Nginx on any Debian-based system (like Ubuntu) with a single command. It’s also good practice to ensure your firewall allows web traffic.

# Install Nginx
sudo apt update
sudo apt install nginx -y

# Allow Nginx through the firewall
sudo ufw allow 'Nginx Full'

To check that it’s running, you can use systemctl:

sudo systemctl status nginx

If it’s active, you can visit your server’s IP address in a web browser, and you should see the default “Welcome to Nginx!” page.

2. Understanding the Nginx Directory Structure

Nginx’s configuration can seem intimidating, but it’s very logical. All the important files live in /etc/nginx/.

• /etc/nginx/nginx.conf: The main configuration file. You will rarely need to edit this file directly.
• /etc/nginx/sites-available/: This is where you will store the configuration files for each of your websites. Think of it as a library of all possible sites you could host.
• /etc/nginx/sites-enabled/: This directory contains symbolic links (shortcuts) to the files in sites-available. Nginx only reads the configurations in this sites-enabled directory. This setup allows you to easily turn websites on and off without deleting their configuration.

3. Setting Up Your First Site (A Server Block)

Let’s host a website for a domain you own, your-domain.com. First, ensure you have pointed your domain to your server’s IP address using an A record at your domain registrar.

Step 1: Create a Home for Your Website

It’s standard practice to store website files in the /var/www/ directory.

# Create a directory for your domain
sudo mkdir -p /var/www/your-domain.com/html

# Assign ownership to your current user so you can edit files easily
sudo chown -R $USER:$USER /var/www/your-domain.com/html

Step 2: Create a Sample Page

Let’s create a simple index.html file for Nginx to serve.

echo "<h1>Success! The your-domain.com server block is working!</h1>" > /var/www/your-domain.com/html/index.html

Step 3: Create the Nginx Configuration File

Nginx calls the configuration for a single site a “server block”. We will create a new file in sites-available for our domain.

sudo nano /etc/nginx/sites-available/your-domain.com

Paste in the following configuration. Each line is explained by the comments.

# This defines a server
server {
    # Listen on port 80 (standard HTTP) for both IPv4 and IPv6
    listen 80;
    listen [::]:80;

    # The root directory where the website files are stored
    root /var/www/your-domain.com/html;

    # The order of files to look for when a request comes in
    index index.html index.htm;

    # The domain names this server block should respond to
    server_name your-domain.com www.your-domain.com;

    # This block handles how to find files
    location / {
        # Try to serve the requested file, then a directory, or else show a 404 error
        try_files $uri $uri/ =404;
    }
}

Step 4: Enable Your Site

Now, we need to tell Nginx to actually use this configuration. We do this by creating a symbolic link to the file in the sites-enabled directory.

sudo ln -s /etc/nginx/sites-available/your-domain.com /etc/nginx/sites-enabled/

Step 5: Test and Restart Nginx

It’s very important to test your configuration file for syntax errors before restarting Nginx.

sudo nginx -t

If you see syntax is ok and test is successful, you are good to go. Restart Nginx to apply the changes.

sudo systemctl restart nginx

That’s it! If you now visit http://your-domain.com in your browser, you will see your “Success!” message instead of the default Nginx welcome page.

4. What’s Next?

You have successfully configured Nginx to host a basic website. This is the foundation for hosting any web project. From here, you can:

• Host multiple websites on the same server by creating a new directory and a new server block file for each domain.
• Set up a reverse proxy to pass traffic to applications running on different ports (like Node.js or Python apps).
• Secure your sites with SSL/TLS using a free tool like Certbot to enable HTTPS.

These more advanced topics are covered in our “Advanced VPS Guide: Mastering Nginx, Subdomains, and Reverse Proxies”.

This guide is designed for the absolute beginner. We will walk through the first essential steps to secure your server, get it ready for projects, and host your first website securely with Nginx and a free SSL certificate.

1. Your First Login: The Root User

Your hosting provider will give you an IP address (e.g., 123.45.67.89) and a password for the root user. The root user is the super-administrator with unlimited power. It’s powerful, but also risky to use for everyday tasks.

Step 1: Connect to the Server

Open a terminal on your computer and connect to your server using the ssh command.

ssh root@YOUR_SERVER_IP

Step 2: Change the Root Password

If your provider gave you a temporary password, your first action should be to change it to something strong and unique.

passwd

2. Create Your Own User Account

This is the single most important security step. We will create a standard user account and give it administrative privileges using the sudo command.

Step 1: Create the New User

Replace devuser with a username you like.

adduser devuser

Step 2: Grant Administrative Privileges

Add your new user to the sudo group, which allows it to run commands as the administrator.

usermod -aG sudo devuser

Step 3: Log in as Your New User

Log out of the root account (exit) and log back in with your new credentials.

ssh devuser@YOUR_SERVER_IP

From now on, you should always log in with this user.

3. Update System and Install Essential Tools

Now that you are logged in as your new sudo user, the first actions are to update the server and install some essential tools.

Step 1: Update the System

This command downloads the latest list of available software (update) and then installs those updates (upgrade).

sudo apt update && sudo apt upgrade -y

Step 2: Install Basic Tools

Next, install a few common and useful tools.

sudo apt install curl git vim htop unzip nginx -y

We include Nginx here as it is a lightweight, high-performance web server we will configure later.

4. Set Your Timezone

Correct server time is important for logs and many applications. Find your timezone from the list and set it.

# Find your timezone (press 'q' to quit the list)
timedatectl list-timezones

# Set your timezone (replace with your own)
sudo timedatectl set-timezone Asia/Kolkata

5. Basic Firewall Setup

A firewall is a digital security guard. We will use ufw (Uncomplicated Firewall) to block unwanted traffic.

Step 1: Allow Essential Traffic

This is critical: You must allow SSH traffic, otherwise the firewall will lock you out. We will also allow Nginx traffic.

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'

‘Nginx Full’ allows traffic on both HTTP (port 80) and HTTPS (port 443).

Step 2: Enable the Firewall

Now, turn the firewall on.

sudo ufw enable

6. Host a Website with Nginx

Now we will configure Nginx to serve a website for a domain you own.

Step 0: Point Your Domain to the Server (DNS)

Before Nginx can work, you have to tell the internet that your domain should point to your server’s IP address. You do this at your domain registrar (the company where you bought your domain, like GoDaddy, Namecheap, Google Domains, etc.).

1. Log in to your domain registrar’s website.
2. Find the DNS management page for your domain.
3. You need to create two ‘A’ records:
   • Record 1 (Root Domain):
     • Type: A
     • Host/Name: @ (this symbol represents the root domain itself)
     • Value/Points to: Your server’s IP address (e.g., 123.45.67.89)
     • TTL (Time to Live): Leave as default (often 1 hour).
   • Record 2 (www subdomain):
     • Type: A
     • Host/Name: www
     • Value/Points to: Your server’s IP address (the same one)
     • TTL: Leave as default.

DNS changes can take anywhere from a few minutes to a few hours to update across the internet.

Step 1: Create a Directory for Your Site

We’ll store our website’s files in the /var/www directory.

# Create a directory for your domain
sudo mkdir -p /var/www/your-domain.com/html

# Assign ownership to your user
sudo chown -R $USER:$USER /var/www/your-domain.com/html

Step 2: Create a Sample Page

Let’s create a simple index.html file for testing.

echo "<h1>Hello from my Nginx Site!</h1>" | sudo tee /var/www/your-domain.com/html/index.html

Step 3: Create an Nginx Server Block

Nginx uses “server block” files to know how to handle incoming domains. We’ll create one for our domain.

sudo nano /etc/nginx/sites-available/your-domain.com

Paste the following configuration into the file:

server {
    listen 80;
    listen [::]:80;

    root /var/www/your-domain.com/html;
    index index.html;

    server_name your-domain.com www.your-domain.com;

    location / {
        try_files $uri $uri/ =404;
    }
}

Step 4: Enable the Server Block

We enable the site by creating a symbolic link from this file into the sites-enabled directory.

sudo ln -s /etc/nginx/sites-available/your-domain.com /etc/nginx/sites-enabled/

Now, test your Nginx configuration for errors and restart it.

sudo nginx -t
sudo systemctl restart nginx

Once your DNS has updated, if you visit http://your-domain.com in a browser, you should see your “Hello World” message.

7. Secure Your Site with SSL (HTTPS)

To secure your site, we’ll get a free SSL certificate from Let’s Encrypt using a tool called Certbot.

Step 1: Install Certbot

Certbot has a dedicated Nginx plugin that makes the process simple.

sudo apt install certbot python3-certbot-nginx -y

Step 2: Obtain the SSL Certificate

Run Certbot. It will read your Nginx configuration, see the domain you just set up, and guide you through obtaining the certificate.

sudo certbot --nginx

Certbot will ask for your email, for you to agree to the terms of service, and if you want to redirect all HTTP traffic to HTTPS. It is highly recommended to choose the redirect option.

Step 3: Verify Auto-Renewal

Let’s Encrypt certificates are valid for 90 days. Certbot automatically sets up a task to renew them for you. You can test the renewal process with a dry run.

sudo certbot renew --dry-run

If this runs without errors, you are all set. Your site is now secure and accessible via https://your-domain.com.

To add a subdomain (e.g., blog.your-domain.com), you simply repeat the process: create a new directory in /var/www, create a new server block file in sites-available, enable it, and then run sudo certbot --nginx again.

8. Quick Tips and Best Practices

• Use SSH Keys: Passwords can be cracked. SSH keys are a much more secure way to log in. This is a highly recommended next security step.

• Keep Your System Updated: Get in the habit of running sudo apt update && sudo apt upgrade -y at least once a week.

• Be Careful with Commands: Don’t run scripts or commands from the internet without understanding what they do.

• Use Strong Passwords: The password for your sudo user should be strong and unique.

1. Prerequisites

Before you begin, ensure you have the following:

• A server running a Debian-based Linux distribution.
• sudo or root access to the server.
• A Telegram account.
• curl and jq installed on your server. If you don’t have them, install them now:

  sudo apt-get update && sudo apt-get install -y curl jq
  

2. Create a Telegram Bot

Your alerts will be sent by a Telegram Bot.

Step 1: Talk to BotFather

In your Telegram app, search for the verified BotFather account and start a chat.

Step 2: Create the Bot

Send the /newbot command. Follow the prompts to give your bot a display name and a unique username, which must end in bot.

Step 3: Save the API Token

Once created, BotFather will provide a secret API token. Copy this token and keep it secure; you will need it in the next steps.

3. Get Your Personal Chat ID

The bot needs to know where to send the alerts. This will be your personal Telegram chat.

Step 1: Start a Chat with Your Bot

Search for your new bot in Telegram and send it any message (e.g., /start). This initializes the chat.

Step 2: Retrieve the Chat ID

In your server’s terminal, run the following command. Replace <YOUR_BOT_TOKEN> with the token you saved from BotFather.

curl -s "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates" | jq '.result[0].message.chat.id'

This command will output a long number, which is your Chat ID. Copy it.

4. Create the Notification Script

This shell script will be triggered on login, gather information, and send the alert.

Step 1: Create the Script File

Using a text editor, create a new file for the script:

sudo nano /usr/local/bin/ssh-login-alert.sh

Step 2: Add the Script Content

Paste the following code into the file. Remember to replace the placeholder values for BOT_TOKEN and CHAT_ID with your actual credentials.

#!/bin/bash

# --- Replace with your details ---
BOT_TOKEN="<YOUR_BOT_TOKEN>"
CHAT_ID="<YOUR_CHAT_ID>"
#----------------------------------

# Do nothing if not an interactive session
if [ -z "$PAM_TYPE" ] || [ "$PAM_TYPE" != "open_session" ]; then
    exit 0
fi

# Gather login information
HOSTNAME=$(hostname)
USER=$PAM_USER
IP_ADDRESS=$PAM_RHOST
TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")

# Format the message using Markdown
MESSAGE=$(cat <<EOF
🔔 *New SSH Login Detected* 🔔

*Server:* \`$HOSTNAME\`
*User:* \`$USER\`
*From IP:* \`$IP_ADDRESS\`
*Time:* \`$TIMESTAMP\`
EOF
)

# Send the message via the Telegram API
curl -s --max-time 10 -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendMessage" \
     -d chat_id="$CHAT_ID" \
     -d text="$MESSAGE" \
     -d parse_mode="Markdown" > /dev/null

Step 3: Make the Script Executable

Save the file and make it executable so the system can run it.

sudo chmod +x /usr/local/bin/ssh-login-alert.sh

5. Configure PAM to Trigger the Script

We’ll use the Pluggable Authentication Module (PAM) framework to execute our script whenever a user opens a new SSH session.

Step 1: Edit the SSHD PAM Configuration

Open the PAM configuration file for the SSH daemon:

sudo nano /etc/pam.d/sshd

Step 2: Add the Execution Rule

Add the following line at the very end of the file. This tells PAM to run our script for every session, but our script is smart enough to only act on SSH logins.

# Run script for SSH login notification
session optional pam_exec.so /usr/local/bin/ssh-login-alert.sh

Save and close the file.

6. Test the Setup

You’re all set! To test the notification, log out of your server and log back in via SSH.

exit

ssh your_user@your_server_ip

Within seconds, you should receive a neatly formatted notification on Telegram from your bot. If you don’t, double-check that the BOT_TOKEN and CHAT_ID in your script are correct and that the script is executable.

1. Initial Server Setup

After acquiring a VPS, you’ll get an IP address and root access. Your first steps are to secure the server and create a non-root user for daily operations.

Connect to your server via SSH:

ssh root@YOUR_SERVER_IP

Create a Sudo User

Operating as root is risky. Create a new user and grant administrative privileges.

# Create the new user (replace 'devuser' with your username)
adduser devuser

# Add the user to the 'sudo' group
usermod -aG sudo devuser

Now, set up SSH key authentication for your new user for enhanced security and convenience, then log in as that user.

2. Essential Security and Updates

A public server is a constant target. Secure it immediately.

Configure the Firewall

ufw (Uncomplicated Firewall) makes this easy. We’ll allow SSH, HTTP, and HTTPS traffic.

# Allow OpenSSH (so you don't lock yourself out)
sudo ufw allow OpenSSH

# Allow Nginx to handle web traffic on ports 80 and 443
sudo ufw allow 'Nginx Full'

# Enable the firewall
sudo ufw enable

After enabling, check its status to ensure it’s active and your rules are loaded.

sudo ufw status

Update Your Server

Keep your system’s packages current to patch security vulnerabilities.

sudo apt update && sudo apt upgrade -y

3. Installing and Understanding Nginx

Nginx is the heart of our setup. It’s a high-performance web server that can also act as a reverse proxy, load balancer, and more.

# Install Nginx
sudo apt install nginx -y

While the package should start and enable Nginx automatically, it’s good practice to run the commands explicitly to be sure.

# Start the Nginx service
sudo systemctl start nginx

# Enable Nginx to start automatically on boot
sudo systemctl enable nginx

# Now, check that it's running and enabled
sudo systemctl status nginx

You should see active (running) in the output. Visiting your server’s IP in a browser should also show the Nginx welcome page.

Nginx Configuration Structure

Nginx’s configuration lives in /etc/nginx. The -p flag in the commands below ensures that the command does nothing if the directories already exist.

sudo mkdir -p /etc/nginx/sites-available
sudo mkdir -p /etc/nginx/sites-enabled

The key directories are:

• /etc/nginx/nginx.conf: The main configuration file. You rarely edit this.
• /etc/nginx/sites-available/: Where you store the configuration files for each of your sites (called “server blocks”).
• /etc/nginx/sites-enabled/: Where you create symbolic links to the configurations in sites-available that you want to be active.

This structure lets you easily enable or disable sites without deleting their configuration files.

4. Advanced Hosting: Subdomains and Reverse Proxies

This is where the magic happens. A single server can host a blog, a portfolio website, a web app, and several APIs, all neatly organized using subdomains.

The core concept is the Reverse Proxy. Your Nginx server listens on the standard web ports (80 for HTTP, 443 for HTTPS) and intelligently forwards incoming requests to the correct internal service based on the requested domain or subdomain.

Scenario:

Let’s say we want to set up the following on our server:

1. eknath.dev: A static HTML/CSS website.
2. blog.eknath.dev: A separate project, maybe a Hugo or Jekyll site.
3. api.eknath.dev: A Node.js application running on port 3000.

Step 1: Create Project Directories

Organize your projects in the /var/www directory.

# Create directories for the main site and blog
sudo mkdir -p /var/www/eknath.dev/html
sudo mkdir -p /var/www/blog.eknath.dev/html

# Set correct permissions
sudo chown -R $USER:$USER /var/www/eknath.dev
sudo chown -R $USER:$USER /var/www/blog.eknath.dev

Verify that the directories were created with the correct ownership.

ls -ld /var/www/eknath.dev/
ls -ld /var/www/blog.eknath.dev/

Now, place some placeholder files.

echo "<h1>Welcome to Eknath's Site</h1>" | sudo tee /var/www/eknath.dev/html/index.html
echo "<h1>Welcome to Eknath's Blog</h1>" | sudo tee /var/www/blog.eknath.dev/html/index.html

Step 2: Create Nginx Server Blocks

Now, we create a configuration file for each site in sites-available.

For the main domain (eknath.dev):

sudo nano /etc/nginx/sites-available/eknath.dev

Add the following server block:

server {
    listen 80;
    listen [::]:80;

    server_name eknath.dev www.eknath.dev;

    root /var/www/eknath.dev/html;
    index index.html index.php;

    location / {
        try_files $uri $uri/ =404;
    }
}

For the blog subdomain (blog.eknath.dev):

sudo nano /etc/nginx/sites-available/blog.eknath.dev

Add this configuration:

server {
    listen 80;
    listen [::]:80;

    server_name blog.eknath.dev;

    root /var/www/blog.eknath.dev/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Step 3: Configure the Reverse Proxy for the API

For api.eknath.dev, we’ll proxy requests to our Node.js app, which we assume is running on http://127.0.0.1:3000.

Create the configuration file:

sudo nano /etc/nginx/sites-available/api.eknath.dev

Add the reverse proxy configuration:

server {
    listen 80;
    listen [::]:80;

    server_name api.eknath.dev;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}