Tags

Tags are the primary way to categorize and filter ideas in NeuralRepo. Every idea can have up to 20 tags, and each tag name can be up to 50 characters long.

Creating Tags

Tags are created on the fly when you assign them to an idea. There is no separate “create tag” step — just start using a tag and it exists.

Web

Open an idea and click the + Add Tag button in the sidebar. Type a tag name and press Enter. The tag is created and assigned immediately.

CLI

# Add one or more tags to an idea
nrepo tag <id> <tags...>

# Examples
nrepo tag 42 ai machine-learning
nrepo tag 18 side-project weekend

API

curl -X PATCH https://neuralrepo.com/api/v1/ideas/42 \
  -H "Authorization: Bearer $NREPO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["ai", "machine-learning"]}'

Tag Format

Tags should follow these conventions for best results:

Rule	Example
Lowercase	machine-learning not Machine-Learning
Hyphenated for multi-word	side-project not side project
Max 50 characters	Enforced by the API
Max 20 tags per idea	Additional tags are rejected with a 400 error

Tip

Consistent tag naming makes filtering more effective. Stick to lowercase, hyphenated names like mobile-app, api-design, or revenue-model.

Auto-Classification

Save an idea with no tags and NeuralRepo tags it for you, a few seconds later, as part of the same background pass that generates embeddings and looks for duplicates. Which mechanism runs depends on your plan:

Plan	How it tags	What you get
Pro	An AI classifier (IBM Granite on Workers AI) picks from your 10 most relevant neighbour tags and your 5 most-used tags	1–3 tags, reusing your vocabulary. It may invent one new lowercase, hyphenated tag (max 30 characters) if nothing fits
Free	Tag-borrowing from the ideas it just matched — no AI call, no cost	Up to 3 tags that appear on two or more of its nearest neighbours. A new idea with fewer than two related neighbours stays untagged

Note

Auto-classification only triggers when an idea has zero tags. Provide even one tag and neither mechanism runs — and if you later strip every tag off an idea and edit its text, auto-tagging runs again on the next pass.

Custom Colors

Assign a custom color to any tag to make it visually distinct across the web app — on the kanban board, in search results, and in the mind map.

Web

Click on any tag in the sidebar, then select Edit Color. Choose a color from the picker or enter a hex value directly.

API

curl -X PATCH https://neuralrepo.com/api/v1/tags/1 \
  -H "Authorization: Bearer $NREPO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"color": "#6366f1"}'

Use the tag’s numeric id in the path. Colors must be in #rrggbb hex format.

Filtering by Tag

Find all ideas with a specific tag across every surface.

Web

Click any tag in the left sidebar to filter the idea list. You can select multiple tags to narrow results further.

CLI

# List ideas filtered by tag
nrepo log --tag ai

# Combine with status filter
nrepo log --tag ai --status exploring

API

# Filter ideas by tag
GET /api/v1/ideas?tag=ai

# Multiple tags (intersection)
GET /api/v1/ideas?tag=ai&tag=mobile-app

Bulk Operations

Add or remove a tag from multiple ideas at once using the CLI, or select ideas in the web app and use the bulk toolbar.

# Add a tag to multiple ideas
nrepo tag add ai --ids 1,2,3

# Remove a tag from multiple ideas
nrepo tag remove deprecated --ids 4,5

Caution

Bulk operations are not atomic. Each idea is updated on its own and reported on its own — a bad or unknown ID fails alone while every other idea still changes. The CLI prints a ✓ or ✗ per idea and a final count; the API returns updated, errors, and a per-idea results array. A bulk request takes at most 50 ids.

Listing Tags with Counts

Retrieve all tags in your repository along with the number of ideas each tag is applied to.

API

GET /api/v1/tags

Response:

{
  "tags": [
    { "id": 1, "name": "ai", "color": "#6366f1", "idea_count": 14 },
    { "id": 2, "name": "mobile-app", "color": null, "idea_count": 8 },
    { "id": 3, "name": "side-project", "color": "#f59e0b", "idea_count": 5 }
  ]
}

CLI

Tag listing is not available as a standalone CLI command. Use nrepo log --tag <name> to filter ideas by tag, or use the API or web dashboard to see all tags with idea counts.

Tidying Up

Tags accumulate. Two things help:

• Tags with no ideas are deleted automatically. Whenever a tag is removed from its last idea, the tag itself is cleaned up, so the sidebar never fills with empty labels.
• The AI agent can merge near-duplicate tags — ml and machine-learning, AI and ai. Its cleanup_tags tool compares tag embeddings, proposes clusters above 0.85 similarity, and keeps the most-used name in each. It previews by default; you confirm before anything merges. See Agent Tools.

Limits

Limit	Value
Tags per idea	20
Tag name length	50 characters
Ideas per bulk tag request	50
Color format	#rrggbb hex

The 20-tag cap is enforced when tags are submitted. Merging two ideas unions their tags without re-checking it, so a merged idea can end up carrying more than 20.

Next Steps

Search Combine a tag filter with semantic or keyword search.

Mind Map Tags colour the nodes and drive the map's tag filter.

Agent Tools suggest_tags and cleanup_tags — AI help for a messy tag list.

Tags API List, rename, recolour, and delete tags programmatically.