kazahana is a lightweight desktop client application for Bluesky. This guide explains the names and functions of each screen element.
Supported version: kazahana v2.4.4When you launch the app, the login screen is displayed.
| Item | Description |
|---|---|
| Handle | Enter your Bluesky handle (e.g., user.bsky.social) |
| App Password | Enter the app password generated in Bluesky (format: xxxx-xxxx-xxxx-xxxx) |
| Login button | Logs in with the entered credentials |
The link at the bottom of the screen takes you to Bluesky's app password settings page.
Tip: kazahana uses an "App Password" issued from Bluesky's settings, not your account's regular password.
After logging in, all screens share a common layout.
Displayed at the very top of the screen. It contains the app name "kazahana" and window control buttons (minimize, maximize, close).
| Position | Element | Description |
|---|---|---|
| Left | Reload button | Manually refreshes the timeline |
| Center | Handle display | Shows the handle of the logged-in account |
| Right | Settings icon (โ) | Opens the Settings screen |
Five icons are displayed in a row below the user bar. Clicking each icon switches to the corresponding screen.
| Icon | Screen | Description |
|---|---|---|
| ๐ | Home | Displays the timeline |
| ๐ | Search | Search for users and posts |
| ๐ | Notifications | Displays notifications such as likes and reposts |
| โ๏ธ | Direct Messages | Displays the DM conversation list |
| ๐ค | Profile | Displays your profile |
When there are unread direct messages, a red numbered badge appears on the โ๏ธ icon.
A blue circular button always displayed at the bottom right. Clicking it opens the New Post screen. You can also open the New Post screen by pressing the "n" key while viewing the timeline.
This screen is displayed by clicking the ๐ icon. Posts from users you follow are displayed in chronological order.
| Tab | Description |
|---|---|
| Home | Displays posts from users you follow (always visible) |
| Discover | Displays recommended posts (visibility can be configured) |
| Video | Displays video posts (visibility can be configured) |
The feed tabs shown can be customized from the Settings screen.
| Element | Description |
|---|---|
| Repost label | For reposted content, "โโ reposted" is displayed at the top |
| Avatar | The poster's profile image. Click to open their profile |
| Display name & handle | The poster's display name and handle (@xxx) are shown |
| Elapsed time | Time since posting (e.g., "27m," "2h," "2d") |
| Post body | Text, links, hashtags, etc. |
| Image thumbnail | If the post contains images, thumbnails are displayed |
| Link card | If the post contains a URL, OGP information is displayed in card format |
| Language label | The post's language is shown at the bottom right (e.g., langs: ja) |
| Client name | If enabled in settings, the posting client name (e.g., via kazahana) is displayed |
Action icons are displayed in a row at the bottom of each post card.
| Icon | Click action | Number | Number click action |
|---|---|---|---|
| ๐ฌ Reply | Opens the reply composer | Yes | โ (no list view) |
| ๐ Repost | Immediately reposts | Yes | Displays list of users who reposted |
| โก Like | Toggles like on/off | Yes | Displays list of users who liked |
| "99" Quote | Displays a popup menu | โ | โ |
| ๐ Bookmark | Toggles bookmark on/off | โ | โ |
| โฎ Menu | Opens additional options menu | โ | โ |
Clicking the "99" quote icon displays the following menu.
| Item | Description |
|---|---|
| Quote post | Opens the quote repost composer |
| View quotes | Displays a list of posts that quoted this post |
A blue horizontal bar labeled "โRead up to hereโ" is displayed on the timeline. It indicates where you last viewed, making it easy to see where you left off.
When you scroll down, a blue circular button (โ arrow icon) appears at the bottom left. Clicking it returns you to the top of the feed.
This screen is displayed by clicking the ๐ icon.
| Element | Description |
|---|---|
| Search input field | Enter text and press Enter to search |
| Search history | Previously searched keywords are listed |
| Individual delete (ร) | Each history item can be deleted with the ร button |
| Delete all | Clears all search history at once |
Results are displayed in two tabs: "Posts" and "Users."
| Tab | Description |
|---|---|
| Posts | Posts matching the keyword are displayed in card format (default) |
| Users | Users matching the keyword are listed |
This screen is displayed by clicking the ๐ icon.
New notifications are listed in chronological order. Each includes the action type, the user who performed it, a post preview, and elapsed time.
| Icon | Type | Description |
|---|---|---|
| โค๏ธ | Like | Your post was liked |
| ๐ฌ | Reply | Your post received a reply |
| ๐ค | Follow | Your account was followed |
| ๐ | Repost | Your post was reposted |
| "99" | Quote | Your post was quote-reposted |
| @ | Mention | You were mentioned in another user's post |
| โค๏ธ | Like via repost | Your repost was liked |
| ๐ | Repost via repost | Your repost was reposted |
This screen is displayed by clicking the โ๏ธ icon.
| Element | Description |
|---|---|
| Avatar & display name | The conversation partner's profile information |
| Latest message preview | The beginning of the most recent message |
| Elapsed time | Time since the latest message |
| Unread badge | A green circle with the unread count |
Click a conversation to open the thread. Click the blue โ button at the bottom right to start a new conversation.
| Element | Description |
|---|---|
| โ Back button | Returns to the conversation list |
| Partner info | Avatar, display name, and handle |
| โฎ Menu | Opens additional options menu |
| Load older messages | Click to load older messages |
| Message display area | Partner's messages: left-aligned, gray. Your messages: right-aligned, blue |
| Message input area | Enter text and click the send button (โถ) to send |
Click the ๐ค icon to view your own profile. Click another user's avatar or display name to view theirs.
| Element | Description |
|---|---|
| Banner image | The background image at the top |
| Avatar | A circular profile image |
| Display name & handle | The account's display name and handle |
| Bio | The profile's bio text and links |
| Following | Click to display the list of users you follow |
| Followers | Click to display the list of your followers |
| Post count | Total number of posts (not clickable) |
| Tab | Description |
|---|---|
| Posts | A list of your posts and reposts |
| Replies | A list of your replies |
| Media | Only posts containing images or videos |
| Likes | A list of posts you have liked |
| Bookmarks | A list of your bookmarked posts |
| Starter Packs | A list of starter packs you have created |
A follow action button is displayed at the bottom right of the banner image.
When not following:
A "Follow" button (blue background) is displayed. Click to follow.
When following:
A "Following" button (white background) is displayed. Click to unfollow.
| Item | Description |
|---|---|
| Add/Remove from list | Add or remove the user from a list |
| Mute | Mute the user |
| Block | Block the user |
| Report this user | Report the user |
Note: The "Bookmarks" tab is not displayed in other users' profile content tabs.
| Screen | Right-side display |
|---|---|
| Following list | Status label indicating whether the user follows you back |
| Followers list | "Following" button (if you follow them) |
Clicking the FAB at the bottom right opens the post composer as a modal.
| Element | Description |
|---|---|
| Cancel | Cancels the post and closes the modal |
| Post button | Publishes the post. You can also publish by pressing Alt+Enter (Windows/Linux) or Option+Enter (macOS) |
| Text input area | Enter your post body (placeholder: "What's up?") |
| Character counter | Current count and limit shown at bottom right (0/300) |
| Add images | Attach image files (up to 4, 1MB max each) |
| Add video | Attach a video file (100MB max) |
| Reply scope | Set who can reply via the dropdown |
| Disable quotes | Check to prevent quote reposts |
Clicking a post card opens the post detail screen.
Click "โ Back" to return. The full post body is displayed with expanded link cards and images. The action bar is fully functional.
Replies are displayed in a thread format below the original post in chronological order.
Click the โ icon on the right side of the user bar to open settings.
| Option | Description |
|---|---|
| Light | Light color scheme |
| Dark | Dark color scheme |
| System | Automatically switches based on OS settings |
Sets the auto-refresh interval: "30s," "60s," "90s," or "120s."
Toggle OS desktop notifications for new activity.
Toggle auto-launch on OS startup.
Choose what happens when you click the close (โ) button: "Exit the application" (default) or minimize. The label adapts to the OS: on macOS it reads "Minimize to Dock," and on Windows/Linux it reads "Minimize to system tray." When minimized, right-click the tray icon (or Dock icon on macOS) and select "Exit" / "Quit" to quit the program.
Adjust video playback volume (0โ100%).
Click "Configure displayed feeds >" to manage which feeds appear as tabs on the home screen.
Note: The "Home" tab is always displayed and is not included in this list.
Enable to show the posting client name (e.g., via kazahana) on each post.
| Item | Description |
|---|---|
| Enable adult content | Toggle on/off with the checkbox |
| Per-category settings | Set "Nudity," "Sexual Suggestiveness," "Pornography," and "Graphic Media" to "Hide," "Warn," or "Show" |
Click "Hidden posts >" to view posts hidden by moderation.
Switch the app's UI language using the dropdown.
Click "Log out" to return to the login screen.
| Item | Description |
|---|---|
| Version | Current app version (e.g., kazahana v1.4.0) |
| MIT License | Link to the license |
| README | Link to the app's README |
| Buy the developer a coffee on Ko-fi | Support the developer |
kazahana supports the BSAF protocol (Bluesky Structured Alert Feed), enabling structured filtering of alert bot posts such as earthquake and tsunami warnings.
In Settings, check "Enable kazahana as a BSAF-compatible client." When enabled, a link to "Manage BSAF Bots >" appears below the checkbox.
Guide: For a detailed walkthrough from registration to filter setup, see "How to Register a BSAF Bot."
On the BSAF bot management screen, you can register BSAF-compatible bots using one of two methods:
| Method | Description |
|---|---|
| URL input | Enter the URL of a Bot Definition JSON and click "Fetch." GitHub repository URLs are automatically converted to raw content URLs. |
| Local file | Click "or load from JSON file" to select a local bot-definition.json file. |
Click a registered bot's name to expand its filter settings. Each filter group (e.g., event type, severity, region) can be individually toggled. "Select all" and "Deselect all" buttons are available for each group.
Important: AND-based filtering โ All filter conditions must match for a post to appear. For example, if you set the event type to "earthquake" and the region to "Hokkaido," only earthquake posts targeting Hokkaido will be displayed. Posts about earthquakes in other regions will be filtered out.
BSAF filters are applied to the Home Timeline and Custom Feeds only. On a bot's Profile page, all posts are always displayed without filtering. This means you can visit a bot's profile at any time to review the complete history of alerts, including those outside your current filter settings.
When multiple BSAF bots report the same event (same type, value, time, and target), kazahana automatically collapses duplicates โ only the first bot's post is shown, with a note indicating how many other bots reported the same event.
Click "Unregister" on a bot's expanded panel. This removes the bot from kazahana and automatically unfollows the bot's account.
You can use a bookmarklet to quickly share the page you are currently viewing in your browser to kazahana's compose screen. The page title and URL are automatically filled in, and a link card (OGP preview) is also generated.
If your browser's bookmarks bar is visible, you can drag the button below directly onto it.
If drag-and-drop is not available, copy the code below and paste it as the URL when creating a bookmark manually.
javascript:void(function(){var t=encodeURIComponent(document.title),u=encodeURIComponent(location.href);window.open('kazahana://compose?title='+t+'&url='+u,'_self')})()Ctrl+Shift+B to toggle).Share to kazahana as the name, and paste the bookmarklet code above as the URL.Ctrl+Shift+B, or View → Toolbars → Bookmarks Toolbar).Share to kazahana as the name, and paste the bookmarklet code as the Location (URL).Cmd+Shift+B).Share to kazahana.Note: kazahana must be installed on your computer for the bookmarklet to work. If kazahana is not installed, clicking the bookmarklet will have no effect.