There's a newborn 👶 in the house 🏠, which means my time at a desk has mostly evaporated. These days I'm more likely to be on a walk, at a park, or waiting around at the hospital than sitting in front of my laptop.

So I went looking for a way to keep building my iOS app without the laptop in front of me — ideally hands-free, driven by voice, from the one computer I always have on me: my phone.

But my app needs a real computer

This turned out to be harder than the usual "code from your phone" setup, because I'm not editing a web app on a cloud server. I'm building a native iOS app, and that means Xcode — which only runs on Apple hardware and can't be spun up on some Linux VPS. Whatever I came up with had to reach back to a real Mac to compile, run the simulator, and deploy.

That one constraint shaped everything below. Whatever I came up with had to let my phone drive a Mac, not replace it.

Here's the setup I landed on, what each piece does, and the one problem I still haven't cracked.

What I'm aiming for

Three things had to be true for this to work:

1. Control the Claude Code session running on my Mac, from my phone.
2. Reliable, hands-free voice-to-text on iOS — so I can actually talk to it instead of thumb-typing.
3. Remotely deploy a build to my phone from anywhere. (Spoiler: still unsolved — more on that at the end.)

Here's the flow I was aiming for. The dotted line — pushing a build back to the phone — is the part I haven't cracked yet:

And here's what I actually ended up with:

The rest of this post walks through each piece. I'm driving all of it with Claude Code, Anthropic's CLI agent, running on my Mac.

Happy: Controlling Claude Code from your phone

The piece that makes this possible is Happy (source on GitHub) — an open-source mobile and web client for Claude Code and Codex.

GitHub - slopus/happy: Mobile and Web client for Codex and Claude Code, with realtime voice, encryption and fully featured

Mobile and Web client for Codex and Claude Code, with realtime voice, encryption and fully featured - slopus/happy

GitHubslopus

You run it on your Mac instead of claude, and it wraps a normal Claude Code session so you can pick it up from the Happy app on your phone, desktop, or browser. The bits I care about:

• Remote access — continue the same session from my phone, away from my desk.
• Voice control — "voice-to-action," not just dictation into a text box.
• Push notifications — it pings me when Claude needs input or finishes a task.
• End-to-end encrypted — the relay only passes encrypted blobs; it can't read your session. (Worth knowing, since you are effectively letting a phone drive a shell on your laptop.)
• Multi-session — run several Claude Code instances in parallel.
• Free and self-hostable (MIT licensed) if you'd rather not use their relay.

LocalWhisper: Reliable, free Voice-to-text on iOS

Happy gets my phone talking to my Mac. But to be truly hands-free I needed good voice-to-text, and that's its own rabbit hole.

iPhones come with text-to-speech, but it's super unreliable 😔 and not very configurable. Maybe it will get better with the next version of Siri, but right now it's 💩 👎.

The popular paid options — Wispr Flow, SuperWhisper — work well but are pricey for what I wanted. I also just prefer models that run on-device.💰 👎

What I landed on is LocalWhisper:

• Free, and runs Whisper models entirely on-device.
• No subscription — there's a one-time $5 Pro unlock, and that's it.
• Model choice, optional AI text cleanup, a system keyboard so it works in any app, and self-hosting support.
• Very customizable, you can specify rules and keywords and even post-grammar checks with another model
  

Here are some screenshots:

Putting it together

With both pieces in place, the loop looks like this:

1. I dictate with LocalWhisper, which types straight into the Happy app.
2. Happy relays that to the Claude Code session running on my Mac.
3. Claude Code does the work — and for the iOS-specific parts (building, running the simulator, deploying) it uses XcodeBuildMCP, which gives the agent a clean set of tools to drive Xcode.

So I can be on a walk, talk to my phone, and have an agent compiling my app on a Mac sitting at home.

How I'm actually using it

Honestly? Mostly for planning. That's where the bulk of my time goes anyway — thinking through a feature, breaking it down, arguing with the agent about the approach — and all of that works great from a phone.

I can also compile and build remotely. What I can't do yet is the satisfying part: manual testing on a real device still waits until I'm home in front of the Mac.

The missing piece: getting a build onto my phone instantly

This is the one thing I haven't solved, and it's the dotted line in that first diagram.

The problem: there's no quick way to push a fresh build to my physical phone unless the phone is cabled to the Mac or on the same Wi-Fi. The moment I'm out of the house, that breaks.

What I've tried or considered:

• Xcode Cloud + TestFlight — works, but a build takes 10–15+ minutes round-trip, which kills the fast feedback loop I'm after.
  • use FastLane running locally would work fine in my case
  • 10-15 minutes is not the worst and maybe what I'll end up with anyways
• Tailscale — I tried putting the phone and Mac on the same tailnet so they'd look "local" to each other, but couldn't get a wireless deploy to go through. (If you've made this work, I'd genuinely love to hear how.)
• Xcode's old "deploy to IP address" feature — discontinued.

There are still a couple things I want to try, but TBD!

Conclusion

The setup I've got — LocalWhisper into Happy into Claude Code into Xcode — lets me plan and build my iOS app from basically anywhere, hands-free, which is exactly what I needed right now.

The last mile is getting a build onto my phone when I'm off my home network. If you've solved that for native iOS, come tell me — I'll update this post.

I take a lot of photos and I edit them afterwards. Lately I've been wondering how basic photo editing operations like contrast, saturation, shadows, etc. actually work.

In this post I define investigate how to raise the "shadows" of an image. I'll walk through some programming approaches how to adjust shadows with all the trade-offs.

WDYM "shadow" of an image?

Here's a before/after of an image with the shadows raised using Adobe Lightroom:

When adjusting the "shadows" of an image, we're really trying to bump up the tones on the lower end of the spectrum between the darks and midtones.

We can use LUMINANCE is a weighted average of RGB values to determine "tone" or brightness.

L = 0.2126 * R + 0.7152 * G + 0.0722 * B
(Luminance is between 0 and 1)

Attempt #1: Hard threshold

The most naive approach would be to adjust the luminance values only within shadow luminance range without any smoothing. Here's what some pseudo code might look like:

if (luminance > 0.1 && luminance <= 0.4) {
  # increase the luminance in the shadow range
  r_new = amount * r
  g_new = amount * g
  b_new = amount * b
}

❌ this does brighten the shadows, but results in harsh boundary clipping at the threshold edges (e.g., 0.1 and 0.4). You'll notice visible breaks in the tonal gradient.

Attempt #2: Smooth Blending with a Bell Curve

To solve the boundary clipping at the threshold boundaries, adjusting the shadows with a bell-curve instead should help smooth out the transition.

Pseudo-code:

if (luminance > 0.1 && luminance <= 0.5) {
  # increase the luminance in the shadow range
  r_new = amount * weighted_curve(L) * r
  g_new = amount * weighted_curve(L) * g 
  b_new = amount * weighted_curve(L) * b
}

Using a weighted curve does raise the shadows of the image with less clipping, but there's a flaw this approach:

✅ threshold edges are better (kinda)

❌ darker regions of the image may end up brighter than lighter ones, resulting in an unnatural reversal of contrast.

Pixels that were originally in deep shadow can become brighter than nearby midtones, creating unnatural halos or flattening the depth of the image. Said another way: tonal order is not preserved.

💡New requirement: raising the shadows must preserve the tonal order.

If two values start with x₁ < x₂, then after adjustment, their output should still follow: f(x₁) < f(x₂)

In mathematics terms, this is called monotonicity.

Attempt #3: Preserving tone order

Our goal for raising the shadows is now:

• boost the brightness of pixels within the shadow range
• have smooth blending between at the boundaries of shadow range
• ensure that tonal order is maintained

The solution is to have a target tone line that we use as a reference or anchor for our adjustments. The easiest way to do this is with a tone curve, specifically a gamma curve.

📈 What’s a Gamma Curve?

Gamma curves are widely used in image encoding, tone mapping, and display correction. For our purposes, a gamma curve defines an ideal, perceptually-correct brightness for a given input.

Gamma is an exponent (γ) used to map linear brightness values to nonlinear ones — and vice versa — to match human perception or display behavior.

The equation for a gamma curve is simple:

y=x^γ

When γ < 1, the curve lifts the shadows while keeping the highlights mostly unchanged.

Adjusting shadows with a target curve

Our shadow equation becomes:

output = x + amount* bell_curve(x) * (gamma_curve(x) - x)

• x = original pixel brightness (linear or gamma-encoded)
• gamma_curve(x) = your tone curve (e.g., gamma 0.6)
• bell_curve(x) = how much you want to apply the effect
• strength = global multiplier

We can look at the shadow region and see that the tonal order is preserved. Or in mathematical terms, the slope is always greater than zero:

Here's the Jupyter code for the graph ⬇️

Final image results:

✅ This result is an improvement now that we're able to maintain tone order.
❌ The color has changed; the final image is de-saturated compared to the original

❌ There's considerable grey clipping in the trees

Attempt #4: ...

At this point I was ready to throw in the towel, but

Bonus Attempt #5: Slow but better details

My research lead me down one more path that was better at preserving contrast and fine details: a bilateral filter for shadow lifting.

This approach is more computationally intensive and thus much slower.

The bilateral filter approach is particularly effective for shadow lifting because it can separate large-scale illumination changes from fine details, allowing you to boost shadows without amplifying noise or losing texture information.
- Claude.ai

There's a whole wiki article on bilateral filters, but the TLDR is that a bilateral filter considers both spatial distance and intensity similarity.

We can calculate a weight that is a combination of both: weight = spatial_weight × range_weight

The details of the implementation are quite intense. It's a bunch of matrix logic, but the results are impressive. I leave it to you to generate the code with AI tools, but here's the result:

The contrast and edges are much better preserved. This is the closest to Lightroom quality that I was able to achieve. Unfortunately, it's quite a slow calculation.

Conclusion

When I first tried to understand how "shadow" adjustment works, I found very little clear guidance. Different approaches used various tone curves, masks, and blending models — some even considered neighboring pixels.

The gamma-target approach described here struck a good balance between simplicity, control, and perceptual correctness. It avoids tonal inversion and creates a more natural look.

Bilateral filters are cool, but slow. There are obviously ways to optimize and it would be interesting to see how far one could take it.

Whatever Lightroom is doing under the hood, it’s probably more refined and adaptive — but this is a solid starting point for understanding and building your own tone mapping tools.

Omarchy

An opinionated Arch + Hyprland Setup

Omarchy

Omarchy is DHH's Hyperland Arch config. I'm enjoying a lot more than Hyde already because it has (for me) less insane config and defaults.

This is a working list of the things I'm customizing after installing Omarchy.

Ctrl instead of Capslock

Capslock out of the box calls xcompose for emojis. I prefer to have it by a ctrl key for my dev/tmux/vim workflows.

nvim ~/.config/hyprland/input.conf

change the kb_options value:

kb_options = ctrl:nocaps

Claude, not ChatGPT

Open claude instead of chatgpt

nvim ~/.config/hyprland/bindings.conf

Change the ChatGPT bind to:

bindd = SUPER, A, Claude, exec, $webapp="https://claude.ai"

Zed (Code IDE)

curl -f https://zed.dev/install.sh | sh

Elixir

EDIT: You can now install with the menu: Super Alt Space > Install > Development > Elixir

mise list-all erlang

mise install erlang@[VERSION]

sh ~/.local/share/mise/installs/erlang/[VERSION]/activate

mise list-all elixir

mise install elixir@[VERSION]

mise use -g erlang@[VERSION]

mise use -g elixir@[VERSION]

Screensaver

Instead of the default Omarchy logo. To edit the logo: Super Alt Space > Style > Screen Saver

▄          ▄          ▄          ▄▄
██▄        ██▄        ██▄        ██
████▄      ████▄      ████▄      ██
██ ▀██▄    ██ ▀██▄    ██ ▀██▄    ██
██   ▀██▄  ██   ▀██▄  ██   ▀██▄  ██
██     ▀██▄██     ▀██▄██     ▀██▄██
██       ▀███       ▀███       ▀███
██         ▀█         ▀█         ▀█

Mouse Cursor speed

gsettings set org.gnome.desktop.peripherals.mouse speed 0.5

This is for Wayland, which Hyprland uses.

If you want to learn about photography, Marc Levoy's lectures are some of the best content I've seen. For the mildly experienced photographer (like myself) with an engineering background, his explanations fill in so many gaps with mathematics and physics.

Topics like:

• how do lenses work and what are the limitations?
• how does perspective and depth of field work?
• the history of photography
• and much more

He's a big deal in the field of digital photography, especially with HDR: https://en.wikipedia.org/wiki/Marc_Levoy

There are 18 lectures, and they're all excellent.

Youtube Playlist: https://www.youtube.com/watch?v=y7HrM-fk_Rc&list=PL7ddpXYvFXspUN0N-gObF1GXoCA-DA-7i

This post compares two camera lenses, one with auto focus and one manual focus:

• Sony FE 40mm F2.5G G Lens  (SEL40F25G) with autofocus
• Voigtlander 35mm f/2 Ultron VM manual focus lens (M mount)

The camera I used was Sony's A7Cii.

Why use a manual focus lens?

This is the big question I've been asking myself since Sony cameras are praised for their auto focus capabilities. Ultimately, it boiled down to wanting to try a different way of taking photos.

There are a number of drawbacks to shooting with the manual lens I chose:

• no access to auto focus, which includes auto tracking and a myriad of other features
• shutter priority mode (S) is not useful since the camera doesn't have the ability to auto-control the aperture of the lens.
• no meta information about the lens or focal length is saved in the image
• an M-mount to E-mount adapter is required
• and more

Despite the list of drawbacks, I've loved using a manual focus. The way it forces me to compose photos is really fun. Especially if you take photos where there are objects in the foreground (like through a fence), auto-focus can get in your way unless you know what you're doing.

The lens itself has really warm saturated colors. It's smaller in size (though equivalent in weight).

Comparison

I will compare the raw photos unedited except for cropping/rotating, and lens correction. In both cases, I've used a form of aperture priority (A) mode, where the shutter speed and ISO are automatically decided by the camera. This is how I shoot photos rather than manual to control everything to a precise setting.

My hypothesis going into this was that the final edited photos will look the same, but perhaps feel different. That distinction is subtle, but the approach to taking a photo with manual focus requires more focus and intention, which I've learned to enjoy.

Comparison: Takeaways

• the images are more blue on the Sony (cold), more orange on the Voigtlander (warm)
• vignetting is much more prominent with the Voigtlander lens
• colors more more saturated in the Voigtlander lens
• images with the Sony are more balanced, but also flat
• sharpness is about the same
• the Voigtlander feel more vintage without being edited

Comparison: Edited Photos

Comparing images with editing applied (coloring, lighting, etc) it really starts to come down to preference. The Voigtlander images definitely feel warmer, but that could be corrected in post if desired.

So, auto focus or Manual focus?

I think this really comes down to preference, but the main difference is experiential. It's hard to quantify in a side by side comparison.

In my opinion, the final product doesn't vary substantially. Personally I'm enjoying the Voigtlander MF lens, but maybe that's because it's something different and forces me to pay more attention to the process.

I take a lot of photos and I edit the ones I like in post. Lately I've been wondering how basic photo editing operations like contrast, saturation, exposure, etc. are actually work.

In this post I define image "saturation." Then I'll walk through some programming approaches how to adjust saturation with all the trade-offs.

Image Saturation

The saturation of an image is how vivid or intense the colors are.

Ways to edit image saturation

There are 2 main approaches to adjusting the saturation of an image.

All the code is on Github: https://github.com/nbw/foto/blob/main/src/cmds/saturation.rs

[1] HSV approach: slower but accurate

How it works:

Convert the image from RGB to its HSV (Hue, Saturation, Value) representation. Here's my blog post about what HSV is and how it works.

Once you have an image in HSV value of a pixel, adjust the S value appropriately, then convert back to an RGB pixel.

Pros:

• generally accurate way of adjusting saturation
• easy to rationalize
• preserves hue

Cons:

• compatibly CPU intensive to other approaches
• the conversion from RBG to HSV is a non-linear operation so you can't use things like SIMD to parallelize it at the CPU level

Rust code:

fn apply_hsv_saturation(img: DynamicImage, saturation: f32) -> Result<DynamicImage> {
    let mut out_img: RgbImage = ImageBuffer::new(img.width(), img.height());

    for (x, y, pixel) in img.to_rgb8().enumerate_pixels() {
        let [r, g, b] = pixel.0;
        let (h, s_base, v) = color::rgb_to_hsv(r, g, b);
        let s = (s_base * saturation).clamp(0.0, 1.0);

        let (r, g, b) = color::hsv_to_rgb(h, s, v);
        let new_pixel = image::Rgb([r, g, b]);
        out_img.put_pixel(x, y, new_pixel);
    }

    Ok(DynamicImage::ImageRgb8(out_img))
}

[2] Via Luminance approach: fast but has issues

How it works:

Luminance (L) and Saturation are related concepts; rather than HSV we can use HSL.

Conveniently, luminance can be approximated using the following equation (the ITU-R BT.601 standard, used to calculate the perceived brightness of a color):

L = 0.299 * R + 0.587 * G + 0.114 * B;

then we can calculate the new R', G', B' values using:

R' = L + (R - L) * saturation
G' = L + (G - L) * saturation
B' = L + (B - L) * saturation

Pros:

• fast and good enough for many cases
• linear operation that can be parallelized easily at the CPU level with tools like SIMD.

Cons

• With extreme adjustments can shift the hue in ways that are hard to control

Rust code using luminance approach:

fn apply_luminance_saturation(img: DynamicImage, saturation: f32) -> Result<DynamicImage> {
    let mut out_img: RgbImage = ImageBuffer::new(img.width(), img.height());

    for (x, y, pixel) in img.to_rgb8().enumerate_pixels() {
        let [r, g, b] = pixel.0;
        let r_f = r as f32;
        let g_f = g as f32;
        let b_f = b as f32;
        let luminance = 0.299 * r_f + 0.587 * g_f + 0.114 * b_f;

        let new_pixel = image::Rgb([
            (luminance + (r_f - luminance) * saturation) as u8,
            (luminance + (g_f - luminance) * saturation) as u8,
            (luminance + (b_f - luminance) * saturation) as u8,
        ]);
        out_img.put_pixel(x, y, new_pixel);
    }

    Ok(DynamicImage::ImageRgb8(out_img))
}

Rust code using luminance approach with Simd for performance:

fn apply_luminance_saturation_simd(img: DynamicImage, saturation: f32) -> Result<DynamicImage> {
    let mut out_img_raw = vec![0u8; img.to_rgb8().into_raw().len()];

    // NOTE:assumes Simd lane factor of 4,
    // but this value depends on your hardware!
    let lanes = 4; 

    for (chunk_idx, rgb_chunk) in img
        .to_rgb32f()
        .into_raw()
        .chunks_exact(lanes * 3)
        .enumerate()
    {
        let chunk_start = chunk_idx * lanes * 3;
        let mut r_vals = [0f32; 4];
        let mut g_vals = [0f32; 4];
        let mut b_vals = [0f32; 4];

        for i in 0..lanes {
            r_vals[i] = rgb_chunk[i * 3] as f32;
            g_vals[i] = rgb_chunk[i * 3 + 1] as f32;
            b_vals[i] = rgb_chunk[i * 3 + 2] as f32;
        }

        let r_f = Simd::from_array(r_vals);
        let g_f = Simd::from_array(g_vals);
        let b_f = Simd::from_array(b_vals);

        let luminance =
            Simd::splat(0.299) * r_f + Simd::splat(0.587) * g_f + Simd::splat(0.114) * b_f;

        let sat: Simd<f32, 4> = Simd::splat(saturation);

        let r_out = luminance + (r_f - luminance) * sat;
        let g_out = luminance + (g_f - luminance) * sat;
        let b_out = luminance + (b_f - luminance) * sat;

        for i in 0..lanes {
            out_img_raw[chunk_start + i * 3] = (r_out[i].clamp(0.0, 1.0) * 255.0) as u8;
            out_img_raw[chunk_start + i * 3 + 1] = (g_out[i].clamp(0.0, 1.0) * 255.0) as u8;
            out_img_raw[chunk_start + i * 3 + 2] = (b_out[i].clamp(0.0, 1.0) * 255.0) as u8;
        }
    }

    let out_img = image::RgbImage::from_raw(img.width(), img.height(), out_img_raw)
        .expect("Failed to create image");

    Ok(image::DynamicImage::ImageRgb8(out_img))
}

Comparison of approaches:

Applying a saturation factor of 2.5 with each approach:

HSV

Luminance

Luminance with SIMD

Performance using a 3mb image wise we get:

. ./benchmarks/saturation                             rs    12:27 

hsv     1.71s user 0.12s system 107% cpu 1.704 total

lum     1.02s user 0.11s system 112% cpu 1.010 total

lumsimd 1.11s user 0.15s system 111% cpu 1.121 total

The luminance simd approach is actually slower than without in this instance 🤔 so it would be worth spending time to make some optimizations there. For video processing video files, using SIMD should be a 3-10x speed increase.

I verified the same results on a 25mb image as well.

Conclusion

There are a bunch of way to edit an image's saturation. Each has it's tradeoffs or side-effects.

In the case of editing photos, the photographer's eye is the final judge; it's probably not super important which technique you use if you're adjusting saturation within reasonable limits. In that case, I'd probably opt for whatever is fastest.

Personally, I find saturation to be less useful compared to vibrance, which I'll look at in another post!

This post is about what the HSV (Hue, Saturation, Value) representation of an image is.

If I told you to visualize the color (125, 75, 200), what color do you see? 🤔

🧍When describing a color, as a human of course, you might say things like: “deep red” or “pastel purple” or “bright and muted orange."

🤖 Whereas a computer (and hardware) would say something like: RED: 125, GREEN: 75, BLUE:  200.

What is intuitive for us is different than what is logical for hardware. So in the 1970’s the Hue Saturation Value system (HSL, too) was invented to represent RGB color values in terms more intuitive to humans.

• Hue (H): the color (red, purple, green, ..). It’s a spectrum represented in degrees (red: 0°, green: 120°, blue 240°). 
• Saturation (S): the intensity of the color. When describing a colors, it’s often the adjective.
• Value (V): the brightness.
  • Imagine that you were mixing paint 🎨 to make a color, the “value” would be how much white or black you mixed in (to brighten or darken it).

Consider the following...

• “Light sky blue”: light (V), sky (S), blue (H)
• “Muted deep red”: muted (V), deep (S), red (H)]

A HSV cone is a common way to visualize it:

Converting from RBG to HSV

Let's look at the RBG to HSV equations and try to understand what they're describing. They look complicated at first glance:

(equations reference)

Starting with the easiest:

VALUE: V = Cmax, is the most dominant color, i.e: the highest value (R, G, or B) of an RGB pixel. So if R = 200, and G and B are 100, then V is 200.

SATURATION: S = (Cmax - Cmin)/ Cmax, is the ratio between the highest and lowest RGB value divided by Cmax to normalize the value between 0 to 1. The exception if the pixel is black, in which case we assume 0 saturation.

HUE: H, returns an angle value between 0 to 360.

• If the brightest of the RGB values is Red, we expect the angle to be between 0° to 120°
• If the brightest of the RGB values is Green, we expect the angle to be between 120° to 240°
• If the brightest of the RGB values is Blue, we expect the angle to be between 240° to 360°

Code: RBG to HSV

Here's an implementation of RGB to HSV using rust:

pub fn rgb_to_hsv(r: u8, g: u8, b: u8) -> (f32, f32, f32) {
    let r = r as f32 / 255.0;
    let g = g as f32 / 255.0;
    let b = b as f32 / 255.0;

    let max = r.max(g).max(b);
    let min = r.min(g).min(b);
    let delta = max - min;

    let h = if delta == 0.0 {
        0.0
    } else if max == r {
        60.0 * (((g - b) / delta) % 6.0)
    } else if max == g {
        60.0 * (((b - r) / delta) + 2.0)
    } else {
        60.0 * (((r - g) / delta) + 4.0)
    };

    let h = if h < 0.0 { h + 360.0 } else { h };
    let s = if max == 0.0 { 0.0 } else { delta / max };
    let v = max;

    (h, s, v)
}

Code on github.

Next time...

In my next post, I'll walk through how to adjust the "saturation" of an image, which is easy if you already have the HSV representation of the image.

So you've written a Rust CLI with Clap and you want to update your README.md with details on how to use it. Well, ConnorGray has written a library that does just that:

GitHub - ConnorGray/clap-markdown: Autogenerate Markdown documentation for clap command-line tools

Autogenerate Markdown documentation for clap command-line tools - ConnorGray/clap-markdown

GitHubConnorGray

Problem: clap-markdown generates markdown just fine, but we want to add the output to our README.md without overwriting the entire contents of the file..

Solution: use hidden comments in the README as a placemarker.

1. Add something like the following to your README.md file:

<!-- start: CLI USAGE -->

<!-- end: CLI USAGE -->

2. Add a hidden command to your CLI as suggested by clap-markdown here, which should call a function that looks something like:

pub fn add_cli_cmd_to_readme() -> Result<()> {
    let md = clap_markdown::help_markdown::<Cli>();

    // Read the README.md file
    let mut content = std::fs::read_to_string("README.md")?;

    // Find the start and end markers
    let start = "<!-- start: CLI USAGE -->";
    let end = "<!-- end: CLI USAGE -->";

    // Replace content between markers
    let start_idx = content
        .find(start)
        .ok_or_else(|| anyhow::anyhow!("Could not find start marker"))?;
    let end_idx = content
        .find(end)
        .ok_or_else(|| anyhow::anyhow!("Could not find end marker"))?;

    content.replace_range((start_idx + start.len())..end_idx, &format!("\n\n{}\n", md));

    // Write back to README.md
    std::fs::write("README.md", content)?;

    println!("Markdown help written to README.md");

    Ok(())
}

This function will add the output of clap_markdown your between the place markers in your README.md.

Example

Here's a repo of mine using it: https://github.com/nbw/foto

I run cargo run – cli-readme to generate a new README.md with updated docs.

This is mostly a PSA because things are much easier than they once were before.

1. ❌ ARCH is hard to install and configure! WRONG – Arch is no longer hard to install. There's a nice install wizard that you can now use: Run archinstall when you're installing the OS.
   1. You can install Hyprland as part of the installer (easy!)
   2. to log into Hyprland, you need to start in TTY mode (ctrl + alt + F4) if you've configured a UI login (maybe you installed Plasma too like I did)
   3. FYI: I installed Arch by putting the disk image on a USB stick and loading it via the bootloader
2. ❌ HYPERLAND is hard to install configure: WRONG – if you want a nice setup to try Hyprland already configured then install the [Hyde project](https://github.com/HyDE-Project/HyDE)
   1. once you've installed Hyde, CMD + / shows you shortcuts.
   2. You can configure hotkeys in ~/.config/hypr/keybindings.conf
   3. run hydectl reload to refresh stuff if needed
   4. there's also Archcraft Hyprland that is worth looking at if you don't like Hyde

Here's a good install guide for Arch:

I started my Linux journey on a cheap ThinkPad X1 Carbon Gen 7 and I opted for NixOS as my Linux distro. It's been great, but to spice things up I also tried Hyprland.

Hyprland is a window manager that automatically organizes new windows for you. At the end of it, you basically have a no-mouse setup– or at least you're not dragging around windows. There are other alternatives (like Sway) out there and they all run a bit differently. I'm not an expert on how Hyprland works (and honestly it's not that important), but there are many people out there who've already written articles on the topic.

If you search "hyprland rice" on Youtube, you'll get endless cool setups.

Sidenote: Hyprland has some problematic history

The creator of Hyprland, Vaxxry, has been banned from a number of Linux communities. I leave it to read to search why, but it's not great.

I willingly tried Hyprland knowing a bit about the drama, but that's not an endorsement of the creator.

My Setup

Hyprland looks cool. That is maybe the one great thing about it. It looks and feels super minimalist.

Hyprland is hard, but cool

Part of me wanted to believe I could make it my daily driver, but the learning curve and required setup is a lot to take on (you setup basically everything). For now, I'm pausing on Hyprland 🛑, but maybe I'll revisit it once I'm ready again. I still have my configs, everything is NixOS based, so I can rebuild my existing setup in a single command.

Here are some of the things you have to setup that you'd otherwise get for free with other distros:

• a task bar
• volume control, brightness control
• search (programs, files, etc.)
• lock screen
• network setup
• file viewer
• power on/off
• auto-sleep the computer
• many other things, but basically everything

The other upside/downside of Hyprland is that it's basically runs on hotkeys. You set those hotkeys so that's nice, but nevertheless you have to remember them. If you step away from your Hyprland setup for a bit, it can feel pretty alien when you come back.

Getting Started

There are a number of tutorials out there, but this is the one that got me started:

For my navigation bar, I ended up finding someone else's implementation online then grabbing what I wanted from it:

• Github: https://github.com/SolDoesTech/HyprV4

Unfortunately I spent countless hours watching videos, reading blogs, etc. to figure out a working setup. It just takes time and I can't remember all the resources I used.

I bought a used Thinkpad X1 Carbon Gen 7 laptop to try Linux and find out if it's right for me.

At the time of writing I'm about a month or more into it.

Why Linux?

For a long time I've been a Mac user. For many reasons, it's been a great choice for me as a developer, as someone who makes music, etc.. I still think Mac is a great option, but I've also always wanted to explore Linux.

I think it started off as wanting to understand computers more, but that wasn't really enough. I hardly ever actually do something because it might be good for me. Certainly not if it requires a ton of effort.

For a while now I've been wanting to decouple my dependency from Apple. My experience being a developer with Mac is to keep installing and adding tools until the thing you're working on just works without cleaning up any messes you made a long the way. What I'm left with is a computer that has so many things installed on it that I can't keep track of it all anymore. It just becomes bloated until I either reset my computer or buy a new one.

Also there are some tools that I want to try that work better (or only work) with Linux. Tools like Firecracker Micro VMs. The developer experience overall just seems to work better on Linux (or matches Mac for the most part).

Ultimately, I want to have more control over what my computer is doing. I want the leanest setup for my needs or at least some better record keeping of what tools I've installed.

I can say already that keeping a lean and organized setup has been empowering.

This isn't the first time I've tried to switch

I actually tried switching to Linux last year when I build a desktop computer for the first time (dual boot Linux and Windows). I started with Manjaro, briefly tried Ubuntu, considered Arch, then ended up on Fedora.

For games (Apex, etc) the Linux setup was great. I rarely had any issues, but in the end my Window was just easier when I wanted to use bluetooth, use an Xbox controller, and use some software that I couldn't get on Linux (I'm looking at you Adobe). So although I have a working Linux desktop, I mostly boot it in Windows these days (sorry!).

For work, I'm still on a Mac

I can't see this changing any time soon. Although my work would permit me to use a Linux setup, I'd have to purchase a computer on my own dime since I have a working laptop already. My M2 Macbook Air works great for work, but if I had to reset it to factory settings then I think it would take me weeks to get back to where I am now. It's one of those if it ain't broke don't fix it situations.

Why not Asahi Linux then?

The Asahi Linux project is creating compatibility with Linux and ARM based Macs. It's a really cool project and I've read many posts of it working great. I just feel that I want to get away from Mac hardware entirely and have a clean break without the option to just switch back to MacOS.

And so..

I hope to post updates of my Linux journey.